@node Содействие
@chapter Содействие

Этот проект развивается совместными усилиями. Нам нужна ваша помощь!
Пожалуйста, свяжитесь с нами через @email{guix-devel@@gnu.org} и
@code{#guix} в сети Freenode IRC. Мы приветствуем идеи, принимаем отчёты об
ошибках, патчи и любую помощь проекту. Например, вы можете создавать
описания пакетов  (@pxref{Принципы опакечивания}).

@cindex кодекс поведения, разработчиков
@cindex соглашение разработчика
Мы хотим создать теплую, дружелюбную среду, свободную от оскорблений, чтобы
каждый мог внести свой вклад в меру своих возможностей. Для этого в нашем
проекте используется ``Соглашение для авторов'',  основанное на @url
{https://contributor-covenant.org/}. Вы можете найти локальную версию в
файле @file{CODE-OF-CONDUCT} в исходном репозитории.

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

@menu
* Сборка из Git::    Новейший и величайший.
* Запуск Guix перед его установкой::  Хакерские 
                                                                трюки.
* Совершенная установка::  Правильные 
                                                 инструменты.
* Принципы опакечивания::  Разрастание 
                                                 дистрибутива.
* Стиль кодирования::  Гигиена участника.
* Отправка исправлений::  Поделитесь своей 
                                               работой.
* Отслеживание ошибок и патчей::  Keeping it all 
                                                             organized.
* Доступ к коммитам::  Внесение изменений в 
                                        официальный 
                                        репозиторий.
* Обновление пакета Guix::  Обновление 
                                              описания пакета 
                                              guix.
* Writing Documentation::    Improving documentation in GNU Guix.
* Тестирование Guix.::  Заставьте Guix говорить 
                                      на вашем родном языке.
@end menu

@node Сборка из Git
@section Сборка из Git

Если вы собираетесь хакать сам Guix, рекомендуется использовать последнюю
версию из репозитория Git:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex аутентификация для проверки Guix
Как убедиться, что вы получили подлинную копию репозитория? Для этого
запустите @command{guix git authenticate}, передав ему коммит и отпечаток
ключа OpenPGP @dfn{channel introduction} (@pxref{Запуск guix git authenticate}):

@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================

@c The commit and fingerprint below must match those of the channel
@c introduction in '%default-channels'.
@example
git fetch origin keyring:keyring
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@noindent
Эта команда возвращает нуль в случае успеха; в противном случае будет
напечатано сообщение об ошибке и команда завершит работу, вернув ненулевой
код.

Как видите, здесь возникает проблема курицы и яйца: сначала вам нужно
установить Guix. Обычно вы устанавливаете Guix System (@pxref{Установка системы}) или Guix поверх другого дистрибутива (@pxref{Бинарная установка}); в любом случае вы должны проверить подпись OpenPGP на
установочном носителе.  Это ``запускает'' (``bootstraps'') цепочку доверия.

Самый простой способ установить развернуть среду разработки для Guix — это,
конечно, использовать Guix! Следующая команда запустит новую оболочку во
всеми зависимостями и необходимыми переменными окружения:

@example
guix shell -D guix --pure
@end example

Подробные сведения об этой команде см. в @xref{Запуск guix shell}.

Если вам Guix не удаётся использовать при сборке из чекаута, установите
следующие пакеты в дополнение к тем, что были указаны в инструкции по
установке (@pxref{Требования}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
@item @url{https://gnu.org/software/automake/, GNU Automake};
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
@item @url{https://www.graphviz.org/, Graphviz};
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

В Guix дополнительные зависимости можно добавить, запустив @command{guix
shell}:

@example
guix shell -D guix help2man git strace --pure
@end example

From there you can generate the build system infrastructure using Autoconf
and Automake:

@example
./bootstrap
@end example

If you get an error like this one:

@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example

@noindent
это означает, скорее всего, что Autoconf не смог найти файл @file{pkg.m4},
который предоставляется pkg-config. Убедитесь, что файл @file{pkg.m4}
доступен. То же относится к @file{guile.m4}, набору макросов,
предоставляемых Guile. Например, если вы установили Automake в
@file{/usr/local}, он не будет искать файлы @file{.m4} в
@file{/usr/share}. Тогда нужно выполнить следующую команду:

@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example

см. @xref{Macro Search Path,,, automake, The GNU Automake Manual}, чтобы
получить больше информации.

Then, run:

@example
./configure --localstatedir=/var
@end example

@noindent
... where @file{/var} is the normal @code{localstatedir} value (@pxref{Хранилище}, for information about this).  Note that you will probably not run
@command{make install} at the end (you don't have to)  but it's still
important to pass the right @code{localstatedir}.

Finally, you can build Guix and, if you feel so inclined, run the tests
(@pxref{Запуск набора тестов}):

@example
make
make check
@end example

@noindent
If anything fails, take a look at installation instructions
(@pxref{Установка}) or send a message to the @email{guix-devel@@gnu.org,
mailing list}.

После этого вы можете аутентифицировать все проверенные коммиты, запустив:

@example
make authenticate
@end example

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

Или, если ваша конфигурация для локального git репозиотория не соответствует
конфигурации по умолчанию, вы можете укащать ссылку для ветки @code{keyring}
с помощью переменной @code{GUIX_GIT_KEYRING}. В следующем примере
предполагается, что у ваш git remote с именем @samp{myremote}, указывающий
на официальный репозиторий:

@example
make authenticate GUIX_GIT_KEYRING=myremote/keyring
@end example

@quotation Примечание
Рекомендуется запускать @command{make authenticate} после каждого вызова
@command{git pull}. Это гарантирует, что вы продолжаете получать актуальные
изменения в репозитории.
@end quotation

After updating the repository, @command{make} might fail with an error
similar to the following example:

@example
error: failed to load 'gnu/packages/dunst.scm':
ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
@end example

This means that one of the record types that Guix defines (in this example,
the @code{origin} record) has changed, and all of guix needs to be
recompiled to take that change into account.  To do so, run @command{make
clean-go} followed by @command{make}.

@node Запуск Guix перед его установкой
@section Запуск Guix перед его установкой

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

С этой целью можно использовать все инструменты командной строки, даже если
вы не запускали @code{make install}.  Для этого вам сначала нужно создать
окружение со всеми доступными зависимостями (@pxref{Сборка из Git}), и
затем просто начните каждую команду с @command{./pre-inst-env} (скрипт
@file{pre-inst-env} находится на верху дерева сборки Guix; он генерируется
запуском @command{./bootstrap}, за которым следует @command{./configure}).
В качестве примера, вот как вы собрали бы пакет @code{hello}
(подразумевается, что @command{guix-daemon} уже запущена на вашей системе;
ничего страшного, если это другая версия):

@example
$ ./pre-inst-env guix build hello
@end example

@noindent
Аналогично, пример для Guile сессии с использованием модулей Guix:

@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

;;; ("x86_64-linux")
@end example

@noindent
@cindex REPL
@cindex цикл чтение-вычисление-вывод
@dots{} and for a REPL (@pxref{Using Guix Interactively}):

@example
$ ./pre-inst-env guile
scheme@@(guile-user)> ,use(guix)
scheme@@(guile-user)> ,use(gnu)
scheme@@(guile-user)> (define snakes
                       (fold-packages
                         (lambda (package lst)
                           (if (string-prefix? "python"
                                               (package-name package))
                               (cons package lst)
                               lst))
                         '()))
scheme@@(guile-user)> (length snakes)
$1 = 361
@end example

Если вы изучаете демона и его исзодники, или если @command{guix-daemon} еще
не запущена в вашей системе, вы можете запустить его прямо из дерева
сборки@footnote{Флаг @option{-E} команды @command{sudo} гарантирует, что
@code{GUILE_LOAD_PATH} настроен правильно, так что @command{guix-daemon} и
инструменты, которые он использует, могут найти необходимые им модули
Guile.}:

@example
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
@end example

Скрипт @command{pre-inst-env} устанавливает все переменные окружения,
которые необходимы для этой задачи, включая @env{PATH} и
@env{GUILE_LOAD_PATH}.

Заметим, что @command{./pre-inst-env guix pull} @emph{не} обновляет
локальное дерево исходников. Эта команда только обновляет символическую
ссылку @file{~/.config/guix/current} (@pxref{Запуск guix pull}). Выполните
@command{git pull}, если вы хотите обновить локальное дерево исходников.

Sometimes, especially if you have recently updated your repository, running
@command{./pre-inst-env} will print a message similar to the following
example:

@example
;;; note: source file /home/user/projects/guix/guix/progress.scm
;;;       newer than compiled /home/user/projects/guix/guix/progress.go
@end example

This is only a note and you can safely ignore it.  You can get rid of the
message by running @command{make -j4}.  Until you do, Guile will run
slightly slower because it will interpret the code instead of using prepared
Guile object (@file{.go}) files.

You can run @command{make} automatically as you work using
@command{watchexec} from the @code{watchexec} package.  For example, to
build again each time you update a package file, run @samp{watchexec -w
gnu/packages -- make -j4}.

@node Совершенная установка
@section Совершенная установка

Совершенная установка для программирования Guix --- это лучший способ
разработки Guix (@pxref{Using Guile in Emacs,,, guile, Guile Reference
Manual}). Во-первых, здесь нужен мощный текстовый редактор, нужен
@url{https://www.gnu.org/software/emacs, Emacs}, дополненный замечательным
@url{https://nongnu.org/geiser/, Geiser}. Чтобы установить это, введите:

@example
guix install emacs guile emacs-geiser emacs-geiser-guile
@end example

Geiser добавляет возможности интерактивной пошаговой разработки внутри
Emacs: компиляция и запуск кода в буферах, доступ к онлайн-документации
(docstrings), контекстные дополнения, @kbd{M-.} для перемещения к
определениям объектов, REPL для тестирования кода и многое другое
(@pxref{Введение,,, geiser, Geiser User Manual}). Для удобной разработки
Guix обязательно настройте Guile для загрузки файлов из вашей инстанции:

@lisp
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(with-eval-after-load 'geiser-guile
  (add-to-list 'geiser-guile-load-path "~/src/guix"))
@end lisp

Вообще, для редактирования кода, в Emacs уже есть Scheme mode.  Но также
обратите внимание на @url{https://www.emacswiki.org/emacs/ParEdit,
Paredit}. Данный пакет предоставляет средства для непосредственной работы с
синтаксическим деревом, такие как объявление s-выражений, их упаковка,
отклонение следующего s-выражения и т.д.

@cindex сниппеты кода
@cindex шаблоны
@cindex сокращение шаблонов
We also provide templates for common git commit messages and package
definitions in the @file{etc/snippets} directory.  These templates can be
used to expand short trigger strings to interactive text snippets. If you
use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you may want
to add the @file{etc/snippets/yas} snippets directory to the
@var{yas-snippet-dirs} variable.  If you use
@url{https://github.com/minad/tempel/, Tempel}, you may want to add the
@file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in
Emacs.

@lisp
;; @r{Assuming the Guix checkout is in ~/src/guix.}
;; @r{Yasnippet configuration}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
;; @r{Tempel configuration}
(with-eval-after-load 'tempel
   ;; Ensure tempel-path is a list -- it may also be a string.
   (unless (listp 'tempel-path)
     (setq tempel-path (list tempel-path)))
   (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
@end lisp

Тексты сообщений коммитов зависят от отображения затронутых файлов
@url{https://magit.vc/, Magit}. Во время редактирования сообщения коммита
типа @code{add} нажмите @kbd{TAB} после его ввода, чтобы вставить шаблон
сообщения коммита добавления пакета; редактируя тип @code{update}, нажмите
@kbd{TAB}, чтобы вставить шаблон обновления пакета; тип @code{https} -
кнопка @kbd{TAB} вставит шаблон изменения адреса домашней страницы пакета на
HTTPS.

Основной код для @code{scheme-mode} вызывается при вводе @code{package...} и
кнопки @kbd{TAB}. Этот код также вставляет строку триггера @code{origin...},
который может быть расширен в дальнейшем. Код @code{origin...}, в свою
очередь, может вставить строки других триггеров, завершающихся @code{...},
который также может быть расширен в дальнейшем.

@cindex внести или обновить авторские права
@cindex @code{M-x guix-copyright}
@cindex @code{M-x copyright-update}
Мы дополнительно обеспечиваем автоматическое обновление информации об
авторских правах в @file{etc/copyright.el}.  Вы можете указать свое полное
имя, почту и загрузить файл.

@lisp
(setq user-full-name "Alice Doe")
(setq user-mail-address "alice@@mail.org")
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(load-file "~/src/guix/etc/copyright.el")
@end lisp

Чтобы ввести авторское право в текущей строке, вызовите @code{M-x
guix-copyright}.

Для обновления авторских прав необходимо указать
@code{copyright-names-regexp}.

@lisp
(setq copyright-names-regexp
      (format "%s <%s>" user-full-name user-mail-address))
@end lisp

Вы можете проверить актуальность своих авторских прав, вызвав @code{M-x
copyright-update}. Если вы хотите делать это автоматически после каждого
сохранения в буфер, то добавьте @code{(add-hook 'after-save-hook
'copyright-update)} в Emacs.

@node Принципы опакечивания
@section Принципы опакечивания

@cindex создание, пакетов
Дистрибутив GNU - в процессе возникновения и может не содержать ваши любимые
пакеты. Этот раздел описывает как можно помочь с развитием дистрибутива.

Пакеты свободного программного обеспечения обычно распространяются в виде
@dfn{архивов исходного кода} (файлы @file{tar.gz}), которые содержат все
исходные файлы. Добавить пакет в дистрибутив означает, по существу, две
вещи: добавление @dfn{рецепта}, в котором обозначено, как собирать пакет,
включая список других пакетов, необходимых для сборки данного, а также
добавление @dfn{метаданных пакета} вместе с рецептом, как например, описание
информации о лицензировании.

В Guix вся эта информация включена в @dfn{определения пакетов}. Определения
пакетов представляют собой высокоуровневый обзор пакета. Они написаны с
использованием синтаксиса языка программирования Scheme. Для каждого пакета
задаётся набор переменных, которые составляют определение пакета, и затем
это определение пакета экспортируется из модуля (@pxref{Пакетные модули}). Однако основательные знания Scheme @emph{not} не обязательны для
создания пакетов. Для информации об определении пакетов см. @pxref{Описание пакетов}.

Когда определение пакета создано, сохранено в файле в дереве исходников
Guix, оно может быть протестировано командой @command{guix build}
(@pxref{Запуск guix build}). Например, допустим, новый пакет называется
@code{gnew}, тогда можно запустить эту команду из дерева сборки Guix
(@pxref{Запуск Guix перед его установкой}):

@example
./pre-inst-env guix build gnew --keep-failed
@end example

Использование @code{--keep-failed} помогает при отладке ошибок сборки, так
как эта опция предоставляет доступ к дереву неудачных сборок. Другая
полезная опция командной строки при отладке - @code{--log-file}, которая
даёт доступ к логу сборки.

Если пакет не известен команде @command{guix}, это может означать, что файл
исходника содержит синтаксическую ошибку или не имеет предложения
@code{define-public}, которое экспортирует переменную пакета. Чтобы
разобраться, можно загрузить модуль из Guile и получить больше информации о
текущей ошибке:

@example
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
@end example

Если ваш пакет собирается без ошибок, пришлите нам свой патч
(@pxref{Отправка исправлений}). Если вам нужна помощь, мы будем рады помочь
вам со своей стороны. После фиксации патча в репозитории Guix новый пакет
будет автоматически собран для всех поддерживаемых платформ нашей
@url{https://@value{SUBSTITUTE-SERVER-1} CI-системой}.

@cindex заменяющий
Пользователи могут получать новые доступные определения пакетов простым
запуском @command{guix pull} (@pxref{Запуск guix pull}). Если
@code{@value{SUBSTITUTE-SERVER-1}} выполнил сборку пакета, установка пакета
выполнит автоматическое скачивание бинарных файлов оттуда
(@pxref{Подстановки}). Единственное место, где нужна активность человека, -
обзор и применение патча.


@menu
* Свобода программного обеспечения::  Что 
                                                                      может 
                                                                      быть 
                                                                      принято 
                                                                      в 
                                                                      дистрибутив.
* Как называть пакеты::  Что может быть в 
                                            имени?
* Номера версий::  Когда имени не 
                                 достаточно.
* Краткие обзоры и описания::  Помощь 
                                                       пользователю 
                                                       в поиске 
                                                       нужного 
                                                       пакета.
* Сниппеты против Фаз::  Где использовать 
                                            сниппет, а где фазу 
                                            сборки.
* Пакеты Emacs::       Ваш Elisp фикс.
* Модули Python::      Английский юмор.
* Модули Perl::        Жемчужинки.
* Пакеты Java::        Кофе-брейк.
* Rust Crates пакеты::  Остерегайтесь окисления.
* Elm Packages::             Trees of browser code
* Шрифты::             Любителям шрифтов.
@end menu

@node Свобода программного обеспечения
@subsection Свобода программного обеспечения

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex свободное программное обеспечение
Операционная система GNU разработана, чтобы пользователи имели свободу при
работе за компьютером. GNU --- это @dfn{свободное программное обеспечение},
то есть пользователи могут иметь
@url{http://www.gnu.org/philosophy/free-sw.html,четыре важнейшие свободы}:
запускать программу, изучать и изменять исходный код программы,
распространять самостоятельно точные копии и распространять изменённые
версии. Пакеты, включенные в дистрибутив GNU, поставляют только программное
обеспечение, которое даёт эти четыре свободы.

Также дистрибутив GNU следует
@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,рекомендациям
для свободных дистрибутивов}. Эти рекомендации, среди прочих указаний, также
отклоняют несвободные встроенные программы, рекомендации несвободного
программного обеспечения и содержат доводы о том, как взаимодействовать с
торговыми марками и патентами.

Но тем не менее, некоторые источники пакетов в оригинале содержат небольшие
необязательные компоненты, которые нарушают указанные рекомендации,
например, это может быть несвободный код. Если это происходит, такие
компоненты удаляются применением соответствующих патчей или сниппетов в
@code{исходный} код пакета @pxref{Описание пакетов}). Так @code{guix build
--source} возвращает "восстановленный свободный" исходный код вместо
изначального исходника.


@node Как называть пакеты
@subsection Как называть пакеты

@cindex имя пакета
Пакет, в действительности, имеет два имени, ассоциированных с ним: первое
--- это имя @emph{переменной Scheme}, которая указана в
@code{define-public}. Это имя делает пакет доступным в коде Scheme,
например, может использоваться как входные данные другого пакета. Второе ---
это строка в поле @code{name} в определении пакета. Это имя используется
командами управления пакетами, например, @command{guix package} и
@command{guix build}.

Оба обычно представляют собой строки в нижнем регистре, содержащие имя
оригинального проекта с дефисами вместо символов нижнего
подчёркивания. Например, GNUnet доступен как @code{gnunet}, а SDL_net ---
как @code{sdl-net}.

Заслуживающим внимания исключением из этого правила является случай, когда
имя проекта состоит только из одного символа, или если уже существует более
старый поддерживаемый проект с таким же именем---независимо от того, был ли
он уже упакован для Guix.  Пользуйтесь здравым смыслом, чтобы сделать такие
имена однозначными и значимыми.  Например, пакет Guix для оболочки (shell)
под названием ``s ''---это @code{s-shell} и @emph{нет} @code{s}.  Не
стесняйтесь обращаться к своим коллегам-хакерам за вдохновением.

Мы не добавляем приставку @code{lib} для пакетов библиотек, несмотря на то,
что это уже часть официального имени пакета. Но для @pxref{Модули Python} и
@ref{Модули Perl} есть исключения, касающиеся модулей для языков Python и
Perl.

При именовании пакетов шрифтов имена меняются, @pxref{Шрифты}.


@node Номера версий
@subsection Номера версий

@cindex версия пакета
Обычно мы опакечиваем только последнюю версию некоторого программного
обеспечения. Но иногда, например, при наличии несовместимых версий
библиотек, нужны две (или более) версии одного пакета. Это требует разных
имён переменных Scheme. Мы используем имя, определённое в @ref{Как называть пакеты}, для самой последней версии; предыдущие версии используют такое же
имя с добавлением @code{-} и номера версии, что позволяет отличить две
версии.

Имя внутри описания пакета остаётся одно для всех версий пакета и не
содержит номера версии.

Например, версии GTK+ 2.24.20 и 3.9.12 могут опакечиваться так:

@lisp
(define-public gtk+
  (package
    (name "gtk+")
    (version "3.9.12")
    ...))
(define-public gtk+-2
  (package
    (name "gtk+")
    (version "2.24.20")
    ...))
@end lisp
Если нам также нужен GTK+ 3.8.2, он будет размещён в пакете
@lisp
(define-public gtk+-3.8
  (package
    (name "gtk+")
    (version "3.8.2")
    ...))
@end lisp

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
@c for a discussion of what follows.
@cindex номер версии, для снимков СКВ
Порой мы опакечиваем снепшоты исходников из системы контроля версий (СКВ)
вместо официальных релизов. Это остаётся исключением, потому что только
разработчики оригинальных программ решают, что является стабильным
релизом. Иногда это имеет значение. Что же мы должны писать в поле
@code{версия}?

Ясно, что нужно сделать отображение идентификатора коммита снепшота СКВ
внутри строки версии, но мы также должны убедиться, что строка "версия"
монотонно увеличивается, так чтобы @command{guix package --upgrade} могла
определить, какая версия новее. Так как идентификаторы коммитов, что точно,
Git, не увеличиваются, мы добавляем номер ревизии, которую мы увеличиваем
каждый раз, когда мы обновляем до нового снепшота. Результирующая строка
версии выглядит так:

@example
2.0.11-3.cabba9e
  ^    ^    ^
  |    |    `-- ID коммита оригинала
  |    |
  |    `--- версия пакета Guix 
  |
последняя версия оригинала
@end example

It is a good idea to strip commit identifiers in the @code{version} field
to, say, 7 digits.  It avoids an aesthetic annoyance (assuming aesthetics
have a role to play here) as well as problems related to OS limits such as
the maximum shebang length (127 bytes for the Linux kernel).  There are
helper functions for doing this for packages using @code{git-fetch} or
@code{hg-fetch} (see below).  It is best to use the full commit identifiers
in @code{origin}s, though, to avoid ambiguities.  A typical package
definition may look like this:


@lisp
(define my-package
  (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
        (revision "1"))          ;Guix package revision
    (package
      (version (git-version "0.9" revision commit))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                      (url "git://example.org/my-package.git")
                      (commit commit)))
                (sha256 (base32 "1mbikn@dots{}"))
                (file-name (git-file-name name version))))
      ;; @dots{}
      )))
@end lisp

@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
Return the version string for packages using @code{git-fetch}.

@lisp
(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
@result{} "0.2.3-0.93818c9"
@end lisp
@end deffn

@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
Return the version string for packages using @code{hg-fetch}.  It works in
the same way as @code{git-version}.
@end deffn

@node Краткие обзоры и описания
@subsection Краткие обзоры и описания

@cindex описание пакета
@cindex краткий обзор пакета
Как мы видели ранее, каждый пакет в GNU@tie{}Guix включает краткое описание
и полное описание (@pxref{Описание пакетов}). Краткие описания и полные
описания важны: по ним производится поиск @command{guix package --search}, и
это важная информация, которая помогает пользователям определить, насколько
пакет соответствует их потребностям. Следовательно, пакеты должны отвечать
требованиям, предъявляемым к ним.

Краткие описания должны начинаться с прописной буквы и не должны
заканчиваться точкой. Они не должны начинаться с артикля (англ. "a" или
"the"), что обычно ничего не значит; например, лучше начать "File-frobbing
tool" вместо "A tool that frobs files".  Краткое описание должно сообщать о
том, что представляет собой пакет, то есть: "Основные утилиты GNU (файлы,
текст, оболочка)", - или для чего он используется, то есть краткое описание
для GNU@tie{}grep таково: "Печать строк, содержащих паттерн".

Помните, что краткое описание должно быть понятным для очень широкой
аудитории. Например, "Манипулирование выравниванием в формате SAM" может
быть понятно продвинутым исследователям в области биоинформатики, но
совершенно бесполезно или может ввести в заблужение не специалистов. Хорошая
идея --- включать в краткое описание идею группы приложений, к которой
относится пакет. В данном примере можно предложить такой вариант:
"Манипулирование выравниванием нуклеотидных последовательностей", что, в
целом, даёт пользователю лучшее представление о том, на что они смотрят.

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

@cindex Разметка Texinfo, в описаниях пакетов
Descriptions can include Texinfo markup, which is useful to introduce
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks
(@pxref{Overview,,, texinfo, GNU Texinfo}).  However you should be careful
when using some characters for example @samp{@@} and curly braces which are
the basic special characters in Texinfo (@pxref{Special Characters,,,
texinfo, GNU Texinfo}).  User interfaces such as @command{guix show} take
care of rendering it appropriately.

Синопсисы и описания перевелены волонтерами
@uref{https://translate.fedoraproject.org/projects/guix/packages, at
Weblate} чтобы как можно больше пользователей могли читать их на своем
родном языке.  Пользовательские интерфейсы ищут их и отображают на языке,
заданном текущей локалью.

Чтобы дать возможность @command{xgettext} извлекать их как текст для
перевода, краткие и полные описания  @emph{должны быть буквенными
строками}.  Это означает, что нельзя пользоваться @code{string-append} или
@code{format} при составлении этих строк:

@lisp
(package
  ;; @dots{}
  (synopsis "Эту строку можно переводить")
  (description (string-append "Эта строка " "*не поддерживает*" " перевод.")))
@end lisp

Перевод --- трудоёмкая работа. Как автор пакета, пожалуйста, уделите
внимание краткому и полному описаниям, потому что каждое изменение влечет
дополнительную работу для переводчиков. Чтобы помочь им, можно сделать
рекомендации или инструкции, вставив специальные комментарии, как этот
(@pxref{xgettext Invocation,,, gettext, GNU Gettext}):

@lisp
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. @dots{}")
@end lisp

@node Сниппеты против Фаз
@subsection Сниппеты против Фаз

@cindex сниппеты, где использовать
Граница между использованием сниппета и фазы сборки для изменения исходных
кодов пакета может быть неуловимой. Обычно сниппеты используются для
удаления нежелательных файлов, таких как связанные библиотеки, несвободные
исходники, или для простых замен. Исходник, производный от оригинального
исходника, должен создавать исходник, который можно использовать для сборки
пакета в любой системе, поддерживаемой апстримом пакета. (т.е. действовать
как соответствующий исходник).  В частности, сниппеты не должны встраивать
элементы хранилища в источники; такое исправление лучше производить на
этапах сборки.  Обратитель к @code{origin} документации за дополнительной
информацией (@pxref{Интерфейс origin}).

@node Пакеты Emacs
@subsection Пакеты Emacs

@cindex Пакеты Emacs
@cindex лицензии пакетов
Emacs пакеты должны предпочтительно использовать систему сборки Emacs
(@pxref{emacs-build-system}), для единообразия и преимуществ,
предоставляемых этапами сборки, таких как автоматическое создание файла
автозагрузки и байтовая компиляция исходников.  Поскольку не существует
стандартизированного способа запуска набора тестов для пакетов Emacs, тесты
по умолчанию отключены.  Когда доступен набор тестов, его следует включить,
дав аргументу @code{#:tests?} значение @code{#true}.  По умолчанию команда
для запуска теста---@command{make check}, но может быть использована любая
команда , указанная в аргументе @code{#:test-command}.  Аргумент
@code{#:test-command} ожидает, что список, содержащий команду и ее
аргументы, будет вызван во время @code{check} фазы.

Elisp зависимости пакетов Emacs обычно предоставляются как
@code{propagated-inputs}, если они необходимы во время работы программы.
Что касается других пакетов, зависимости сборки или тестирования должны быть
указаны как @code{native-inputs}.

Пакеты Emacs иногда зависят от каталогов с ресурсами, которые должны быть
установлены вместе с файлами Elisp. Аргумент @code{#:include} можно
использовать для этой цели, указав список совпадающих регулярных выражений.
Лучшая практика при использовании аргумента @code{#:include} заключается в
расширении, а не изменении его значения по умолчанию (доступный через
переменную @code{%default-include} variable).  Например, пакет расширения
yasnippet обычно включает каталог @file{snippets}, который можно скопировать
в каталог установки, используя:

@lisp
#:include (cons "^snippets/" %default-include)
@end lisp

При возникновении проблем целесообразно проверить наличие заголовка
расширения @code{Package-Requires} в основном исходном файле пакета, а также
соответствие перечисленным в нем зависимостям и их версиям.

@node Модули Python
@subsection Модули Python

@cindex python
В настоящее время мы поставляем пакеты Python 2 и Python 3 через переменную
Scheme под именами @code{python-2} и @code{python} в соответствии с
@ref{Номера версий}. Чтобы предотвратить путанницу и конфликты имён других
языков программирования, модули Python содержат слово @code{python}.

Некоторые модули совместимы только с одной версией Python, другие - с
обоими. Если пакет Foo работает только с Python 3, мы называем его
@code{python-foo}. Если он работает только с Python 2, мы называем его
@code{python2-foo}. Если он совместим с обеими версиями, мы создаём два
пакета с соответствующими именами.

Если проект уже содержит слово @code{python}, мы отбрасываем его; например,
модуль python-dateutil опакечен под именем @code{python-dateutil} и
@code{python2-dateutil}. Если имя проекта начинается с @code{py} (т.е.@:
@code{pytz}), мы оставляем такое имя и добавляем префикс, как это описано
выше.

@quotation Примечание
Currently there are two different build systems for Python packages in Guix:
@var{python-build-system} and @var{pyproject-build-system}.  For the longest
time, Python packages were built from an informally specified
@file{setup.py} file.  That worked amazingly well, considering Python's
success, but was difficult to build tooling around.  As a result, a host of
alternative build systems emerged and the community eventually settled on a
@url{https://peps.python.org/pep-0517/, formal standard} for specifying
build requirements.  @var{pyproject-build-system} is Guix's implementation
of this standard.  It is considered ``experimental'' in that it does not yet
support all the various PEP-517 @emph{build backends}, but you are
encouraged to try it for new Python packages and report any problems.  It
will eventually be deprecated and merged into @var{python-build-system}.
@end quotation

@subsubsection Перечисление зависимостей
@cindex входные данные, для пакетов Python

Dependency information for Python packages is usually available in the
package source tree, with varying degrees of accuracy: in the
@file{pyproject.toml} file, the @file{setup.py} file, in
@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for test
dependencies).

Ваша миссия при написании рецепта сборки пакета Python --- отобразить эти
зависимости в должном типе "input" (@pxref{ссылка на пакет, inputs}). Хотя
импортёр @code{pypi} обычно отрабатывает хорошо (@pxref{Запуск guix import}), возможно, вы желаете просмотреть приведённый чек-лист, чтобы
узнать о зависимостях.

@itemize

@item
We currently package Python with @code{setuptools} and @code{pip} installed
per default.  This is about to change, and users are encouraged to use
@code{python-toolchain} if they want a build environment for Python.

@command{guix lint} will warn if @code{setuptools} or @code{pip} are added
as native-inputs because they are generally not necessary.

@item
Зависимости Python, необходимые во время работы, идут в
@code{propagated-inputs}. Они обычно определены с ключевым словом
@code{install_requires} в @file{setup.py} или в файле
@file{requirements.txt}.

@item
Python packages required only at build time---e.g., those listed under
@code{build-system.requires} in @file{pyproject.toml} or with the
@code{setup_requires} keyword in @file{setup.py}---or dependencies only for
testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
@code{native-inputs}.  The rationale is that (1) they do not need to be
propagated because they are not needed at run time, and (2) in a
cross-compilation context, it's the ``native'' input that we'd want.

Примерами являются фреймворки тестирования @code{pytest}, @code{mock} и
@code{nose}. Конечно, если какой-либо из этих пакетов также необходим во
время запуска и работы, его следует указывать в @code{propagated-inputs}.

@item
Всё, что не попало в предыдущие категории, указывается в @code{inputs},
например, программы или библиотеки C, необходимые для сборки пакетов Python,
которые используют расширения C.

@item
Если у пакета Python есть необязательные зависимости
(@code{extras_require}), самостоятельно решите, нужно ли их добавлять в
зависимости от их полезности или избыточности (@pxref{Отправка исправлений,
@command{guix size}}).

@end itemize


@node Модули Perl
@subsection Модули Perl

@cindex perl
Программы Perl именуются как и любой другой пакет, используя исходное имя в
нижнем регистре. Для пакетов Perl, содержащих отдельный класс мы используем
имя класса в нижнем регистре, заменяем все вхождения @code{::} на дефисы и
добавляем приставку @code{perl-}. Так класс @code{XML::Parser} становится
@code{perl-xml-parser}. Модули, содержащие несколько классов, сохраняют свои
изначальные имена в нижнем регистре и также имеют префикс
@code{perl-}. Подобные модули имеют тенденцию писать слово @code{perl}
где-либо в их имени, так что это слово удаляется, так как префикс содержит
это слово. Например, @code{libwww-perl} становится @code{perl-libwww}.


@node Пакеты Java
@subsection Пакеты Java

@cindex java
Программы Java именуются как любой другой пакет, используя исходное им в
нижнем регистре.

Чтобы избежать путанницы и конфликтов имён с другими языками
программирования, желательно именовать пакет, поставляющий программу Java, с
префиксом @code{java-}. Если проект уже содержит слово @code{java}, мы
обрезаем его. Например, пакет @code{ngsjava} опакечивается под именем
@code{java-ngs}.

Для пакетов Java, содержащих отдельный класс или небольшую ирархию, мы
используем имя в нижнем регистре, заменяя все вхождения @code{.} на дефисы,
и указываем префикс @code{java-}. Так класс  @code{apache.commons.cli}
становится пакетом @code{java-apache-commons-cli}.


@node Rust Crates пакеты
@subsection Rust Crates пакеты

@cindex rust
Программы Java именуются как любой другой пакет, используя исходное им в
нижнем регистре.

Чтобы предотвратить конфликты пространства имен, мы используем префикс
@code{rust-} для всех остальных пакетов Rust. Имя должно быть изменено на
строчные буквы, если необходимо, и тире должны остаться на месте.

В экосистеме rust использование нескольких несовместимых версий пакета в
любой момент времени является нормой, поэтому у всех пакетов должен быть
версионный суффикс. Если пакет прошел версию 1.0.0, тогда достаточно только
основного номера версии (например, @:@code{rust-clap-2}), в противном случае
суффикс версии должен содержать как основную, так и вспомогательную версию
(например, @:@code{rust-rand-0,6}).

Из-за сложности повторного использования rust пакетов в качестве
предварительно скомпилированных входных данных для других пакетов система
сборки Cargo (@pxref{Системы сборки, @code{cargo-build-system}}) представляет
@code{#:cargo-input} и ключевые слова @code{cargo-development-input} в
качестве аргументов для системы сборки. Было бы полезно думать о них как о
@code{propagated-inputs} и @code{native-inputs}. Rust @code{dependencies} и
@code{build-dependencies} должны идти в @code{#:cargo-input}, а
@code{dev-dependencies} должен идти в @code{#:cargo-development-input}. Если
пакет Rust ссылается на другие библиотеки, то следует использовать
стандартное размещение в @code{input} и т.п.

Следует позаботиться о том, чтобы была использована корректная версия
зависимостей; с этой целью мы стараемся не пропускать тесты или использовать
@code{#:skip-build?}, когда это возможно. Конечно, это не всегда возможно,
так как пакет может быть разработан для другой операционной системы,
зависить от новых функций компилятора Rust для разработчиков (Nightly), или
тесты могли устареть с момента выпуска.


@node Elm Packages
@subsection Elm Packages

@cindex Elm
Elm applications can be named like other software: their names need not
mention Elm.

Packages in the Elm sense (see @code{elm-build-system} under @ref{Системы сборки}) are required use names of the format
@var{author}@code{/}@var{project}, where both the @var{author} and the
@var{project} may contain hyphens internally, and the @var{author} sometimes
contains uppercase letters.

To form the Guix package name from the upstream name, we follow a convention
similar to Python packages (@pxref{Модули Python}), adding an @code{elm-}
prefix unless the name would already begin with @code{elm-}.

In many cases we can reconstruct an Elm package's upstream name
heuristically, but, since conversion to a Guix-style name involves a loss of
information, this is not always possible.  Care should be taken to add the
@code{'upstream-name} property when necessary so that @samp{guix import elm}
will work correctly (@pxref{Запуск guix import}). The most notable
scenarios when explicitly specifying the upstream name is necessary are:

@enumerate
@item
When the @var{author} is @code{elm} and the @var{project} contains one or
more hyphens, as with @code{elm/virtual-dom}; and

@item
When the @var{author} contains hyphens or uppercase letters, as with
@code{Elm-Canvas/raster-shapes}---unless the @var{author} is
@code{elm-explorations}, which is handled as a special case, so packages
like @code{elm-explorations/markdown} do @emph{not} need to use the
@code{'upstream-name} property.
@end enumerate

The module @code{(guix build-system elm)} provides the following utilities
for working with names and related conventions:

@deffn {Scheme procedure} elm-package-origin @var{elm-name} @var{version} @
  @var{hash} Returns a Git origin using the repository naming and tagging
regime required for a published Elm package with the upstream name
@var{elm-name} at version @var{version} with sha256 checksum @var{hash}.

For example:
@lisp
(package
  (name "elm-html")
  (version "1.0.0")
  (source
   (elm-package-origin
    "elm/html"
    version
    (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
  ...)
@end lisp
@end deffn

@deffn {Scheme procedure} elm->package-name @var{elm-name}
Returns the Guix-style package name for an Elm package with upstream name
@var{elm-name}.

Note that there is more than one possible @var{elm-name} for which
@code{elm->package-name} will produce a given result.
@end deffn

@deffn {Scheme procedure} guix-package->elm-name @var{package}
Given an Elm @var{package}, returns the possibly-inferred upstream name, or
@code{#f} the upstream name is not specified via the @code{'upstream-name}
property and can not be inferred by @code{infer-elm-package-name}.
@end deffn

@deffn {Scheme procedure} infer-elm-package-name @var{guix-name}
Given the @var{guix-name} of an Elm package, returns the inferred upstream
name, or @code{#f} if the upstream name can't be inferred.  If the result is
not @code{#f}, supplying it to @code{elm->package-name} would produce
@var{guix-name}.
@end deffn

@node Шрифты
@subsection Шрифты

@cindex шрифты
Для шрифтов, которые не установлены пользователем, исходя из настроек
печати, или рааспространяемые как часть большого пакета программного
обеспечения, мы применяем обычные правила опакечивания программного
обеспечения. Например, это относится к шрифтам, поставляемым как часть
системы X.Org, или шрифтов TeX Live.

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

Имя пакета, содержащего только одно семейство шрифтов, начинается с
@code{font-}; далее идёт литейное имя и дефис @code{-}, если литейное имя
известно, а затем - имя семейства шрифтов, в котором пробелы заменяются
дефисами (и обычно все буквы в верхнем регистре заменяются на нижний
регистр). Например, семейство шрифтов Gentium от SIL опакечивается под
именем @code{font-sil-gentium}.

Пакет с несколькими семействами шрифтов имеет в названии имя коллекции
вместо имени семейства. Например, шрифты Liberation состоят из трёх
семейств: Liberation Sans, Liberation Serfif и Liberation Mono. Они могли бы
опакечиваться отдельно под именами @code{font-liberation-sans} и так далее,
но так как они распространяются вместе под общим именем, мы предпочитаем
опакечивать их вместе как @code{font-liberation}.

В случае, когда несколько форматов одного семейства щрифтов или коллекции
шрифтов опакечена отдельно, в имени присутствует небольшая отметка о формате
с предваряющим дефисом. Мы используем @code{-ttf} для шрифтов TrueType,
@code{-otf} - для шрифтов OpenType - и  @code{-type1} - для шрифтов
PostScript Type 1.


@node Стиль кодирования
@section Стиль кодирования

В основном наш код следует стандартам кодирования GNU (@pxref{Top,,,
standards, GNU Coding Standards}). Но они не имеют исчерпывающих указаний
для Scheme, так что есть дополнительные правила.

@menu
* Парадигма программирования::  Как 
                                                           компоновать 
                                                           элементы.
* Модули::             Где разместить код?
* Типы данных и поиск образцов::  Использование 
                                                            структур 
                                                            данных.
* Форматирование кода::  Написание 
                                             соглашений.
@end menu

@node Парадигма программирования
@subsection Парадигма программирования

Код Scheme в Guix написан в чисто функциональном стиле. Одно исключение -
это код, который вызывает ввод/вывод и процедуры, которые реализуют
низкоровневые операции, как например, процедура @code{memoize}.

@node Модули
@subsection Модули

Модули Guile, которые вызываются для сборки, должны жить в пространстве имён
@code{(guix build @dots{})}. Они не должны ссылаться на другие модули Guix
или GNU. Однако это нормально, если модуль типа "host-side" использует
модуль типа build-side.

Модули, которые работают во всей системе GNU, должны быть в пространстве
имён @code{(gnu @dots{})}, но не @code{(guix @dots{})}.

@node Типы данных и поиск образцов
@subsection Типы данных и поиск образцов

Правило классического Lisp - использование списков для представления всего и
просмотр списков "вручную", используя @code{car}, @code{cdr}, @code{cadr} и
тому подобное. Возникают некоторые проблемы этого стиля, например, это
тяжело читается, провоцирует ошибки, и создаёт отчёты об ошибках без должной
детализации.

@findex define-record-type*
@findex match-record
@cindex pattern matching
Guix code should define appropriate data types (for instance, using
@code{define-record-type*}) rather than abuse lists.  In addition, it should
use pattern matching, via Guile’s @code{(ice-9 match)} module, especially
when matching lists (@pxref{Pattern Matching,,, guile, GNU Guile Reference
Manual}); pattern matching for records is better done using
@code{match-record} from @code{(guix records)}, which, unlike @code{match},
verifies field names at macro-expansion time.

@node Форматирование кода
@subsection Форматирование кода

@cindex форматирование кода
@cindex стиль кодирования
При написании кода Scheme мы пользуемся мудростью программистов Scheme. В
основном мы следуем  @url{http://mumble.net/~campbell/scheme/style.txt,
Riastradh's Lisp Style Rules}. Этот документ, к счастью, содержит
большинство соглашений, которые применимы также для кода Guile. Это очень
вдумчиая работа, пожалуйста, прочтите её.

Некоторые специальные формы, вводимые в Guix, как например, макрос
@code{substitute*}, имеют специальные правила отступов. Они определены в
файле @file{.dir-locals.el}, которые использует Emacs автоматически. Также
отметим, что Emacs-Guix предоставляет режим @code{guix-devel-mode}, который
вставляет отступы и подсвечивает код Guix должным образом
(@pxref{Разработка,,, emacs-guix, The Emacs-Guix Reference Manual}).

@cindex отступы, в коде
@cindex форматировние, кода
Если вы не пользуетесь Emacs, пожалуйста убедитесь, что ваш редактор знает
эти правила. Для автоматической расстановки отступов можно запустить:

@example
./pre-inst-env guix style @var{package}
@end example

@noindent
@xref{Invoking guix style}, for more information.

@cindex Vim, редактирование кода Scheme
Если вы редактируете код в Vim, мы рекомендуем запустить @code{:set
autoindent}, так отступы будут автоматически вставляться в ваш код, пока вы
печатаете. В дополнение вам может помочь для работы со всеми этими скобками
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}}.

Мы требуем, чтобы все высокоуровневые процедуры содержали строки
документации. Хотя это требование может не учитываться для простых приватных
процедур в пространстве имён @code{(guix build @dots{})}.

Процедуры должны иметь не более четырёх параметров. Передавайте параметры по
ключевым словам в процедурах, которые принимают более четырёх параметров.


@node Отправка исправлений
@section Отправка исправлений

Development is done using the Git distributed version control system.  Thus,
access to the repository is not strictly necessary.  We welcome
contributions in the form of patches as produced by @code{git format-patch}
sent to the @email{guix-patches@@gnu.org} mailing list (@pxref{Submitting patches to a project,,, git, Git User Manual}).  Contributors are encouraged
to take a moment to set some Git repository options (@pxref{Конфигурирование Git}) first, which can improve the readability of patches.  Seasoned Guix
developers may also want to look at the section on commit access
(@pxref{Доступ к коммитам}).

This mailing list is backed by a Debbugs instance, which allows us to keep
track of submissions (@pxref{Отслеживание ошибок и патчей}).  Each message sent
to that mailing list gets a new tracking number assigned; people can then
follow up on the submission by sending email to
@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is the
tracking number (@pxref{Отправка пакета исправлений}).

Пожалуйста, пишите логи коммита в формате ChangeLog (@pxref{Change Logs,,,
standards, GNU Coding Standards}); можно просмотреть историю коммитов,
например.

Перед отправкой патча, который добавляет или изменяет описание пакета,
пожалуйста, выполните следующие проверки:

@enumerate
@item
Если авторы пакета программного обеспечения преоставляют криптографическую
подпись для архива релиза, выполните проверку аутентичности архива. Для
отдельного файла GPG-подписи это можно сделать командой @code{gpg --verify}.

@item
Потратьте немного времени, чтобы предоставить адекватное краткое описание и
полное описание пакета. Смотрите @xref{Краткие обзоры и описания} для
подробностей.

@item
Запустите @code{guix lint @var{package}}, где @var{package} - это имя нового
изменённого пакета, и устраните любые ошибки из отчёта (@pxref{Запуск guix lint}).

@item
Run @code{guix style @var{package}} to format the new package definition
according to the project's conventions (@pxref{Invoking guix style}).

@item
Убедитесь, что пакет собирается на вашей платформе, используя @code{guix
build @var{package}}.

@item
We recommend you also try building the package on other supported
platforms.  As you may not have access to actual hardware platforms, we
recommend using the @code{qemu-binfmt-service-type} to emulate them.  In
order to enable it, add the @code{virtualization} service module and the
following service to the list of services in your @code{operating-system}
configuration:

@lisp
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
@end lisp

И тогда запустите переконфигурирование системы.

Также можно собирать пакеты под различные платформы, обозначив опцию
@code{--system}. Например, чтобы собрать пакет "hello" для архитектур armhf,
aarch64, или mips64 вы должны выполнить соответственно следующее:
@example
"guix build --system=armhf-linux --rounds=2 hello
"guix build --system=aarch64-linux --rounds=2 hello
@end example

@item
@cindex сборка
Убедитесь, что пакет не использует связанные копии программ, которые уже
доступны как отдельные пакеты.

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

@item
Просмотрите отчеты  @command{guix size} (@pxref{Запуск guix size}). Это
позволит найти связь с другими пакетами, сохранившуюся без
необходимости. Это также позволяет решить, как разделить пакет
(@pxref{Пакеты со множественным выходом}) и какие должны использоваться
опциональные зависимости. В частности, это способ избежать использование
большого @code{texlive} как зависимости и использовать @code{texlive-tiny}
или @code{texlive-union} вместо него.

@item
For important changes, check that dependent packages (if applicable) are not
affected by the change; @code{guix refresh --list-dependent @var{package}}
will help you do that (@pxref{Запуск guix refresh}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
@cindex стратегия бренчей
@cindex стратегия планирования пересборки
В зависимости от числа пакетов зависимостей и, как следствие, числа
вызываемых пересборок, коммиты отправляются в разные бренчи следующим
образом:

@table @asis
@item 300 пакетов зависимостей или менее
бренч @code{master} (не разрушающие изменения).

@item от 300 до 1200 пакетов зависимостей
бренч @code{staging} (не разрушающие изменения). Этот бренч предназначен для
включения в @code{master} каждые 3 недели (примерно). Тематические изменения
(т.е. обновление стека GNOME) могут отправляться в специальный бренч,
скажем, @code{gnome-updates}.

@item более 1200 пакетов зависимостей
бренч @code{core-updates} (может включать главные и потенциально
разрушительные изменения). Этот бренч предназначен для включения в
@code{master} каждые 2,5 месяца примерно.
@end table

All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1}, tracked by
our build farm} and merged into @code{master} once everything has been
successfully built.  This allows us to fix issues before they hit users, and
to reduce the window during which pre-built binaries are not available.

@c TODO: It would be good with badges on the website that tracks these
@c branches.  Or maybe even a status page.
Когда мы решим начать сборку веток @code{staging} или @code{core-updates},
они будут форкнуты (forked) и переименованы с суффиксом @code{-frozen},
после чего замороженные ветки будут получать только исправления ошибок.
Ветки @code{core-updates} и @code{staging} остануться открыты для патчей в
следующем цикле.  Если вы не знаете, где разместить патч, спросите в списке
рассылки или в IRC.

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

Простой способ выполнить это - собрать такой же пакет несколько раз подряд
на вашей машине (@pxref{Запуск guix build}):

@example
guix build --rounds=2 my-package
@end example

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

Другой способ --- использовать @command{guix challenge} (@pxref{Запуск guix challenge}). Можно запустить это один раз, когда коммит пакета был
отправлен, и собрать с помощью @code{@value{SUBSTITUTE-SERVER-1}}, чтобы
проверить, что это даёт результат такой же, как у вас.  Ещё лучше найти
другую машину, на которой можно собрать это и выполнить @command{guix
publish}. Так как другая удалённая машина дл сборки отличается от вашей, это
может выявить проблемы, нарушающие детерминизм, связанные с аппаратным
обеспечением, то есть вызванные использованием различных расширений
ассемблера или другого ядра операционной системы, то есть касательно файлов
@code{uname} или @file{/proc}.

@item
При написании документации, пожалуйста, используйте нейтральную по гендеру
лексику, когда речь идёт о людях, как например, тут
@uref{https://en.wikipedia.org/wiki/Singular_they, singular "they"@comma{}
"their"@comma{} "them"} и т.д.

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

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

@item
Please follow our code formatting rules, possibly running @command{guix
style} script to do that automatically for you (@pxref{Форматирование кода}).

@item
Если это возможно, используйте зеркала при указании URL исходников
(@pxref{Запуск guix download}). Используйте надёжные URL'ы, а не
сгенерированные. Например, архивы GitHub не являются идентичными между
поколениями, так что в этом случае часто лучше клонировать репозиторий. Не
используйте поле @command{name} в URL, это не очень удобно: если имя
изменится, тогда URL будет неправильным.

@item
Проверьте, собирается ли Guix (@pxref{Сборка из Git}), и устраните
предупреждения, особенно те, которые касаются использования неопределенных
символов.

@item
Убедитесь, что ваши изменения не ломают Guix и имитируйте @code{guix pull}
вместе с:
@example
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
@end example

@end enumerate

When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
subject, if your patch is to be applied on a branch other than
@code{master}, say @code{core-updates}, specify it in the subject like
@samp{[PATCH core-updates] @dots{}}.

You may use your email client or the @command{git send-email} command
(@pxref{Отправка пакета исправлений}).  We prefer to get patches in plain text
messages, either inline or as MIME attachments.  You are advised to pay
attention if your email client changes anything like line breaks or
indentation which could potentially break the patches.

Когда отправите свой самый первый патч на @email{guix-patches@@gnu.org},
ожидайте некоторой задержки. Вам нужно подождать, пока вы не получите
подтверждение с присвоенным номером отслеживания. Дальнейшие подтверждения
не следует откладывать.

When a bug is resolved, please close the thread by sending an email to
@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.

@node Конфигурирование Git
@subsection Конфигурирование Git
@cindex git configuration
@cindex @code{git format-patch}
@cindex @code{git send-email}

If you have not done so already, you may wish to set a name and email that
will be associated with your commits (@pxref{telling git your name, ,
Telling Git your name, git, Git User Manual}).  If you wish to use a
different name or email just for commits in this repository, you can use
@command{git config --local}, or edit @file{.git/config} in the repository
instead of @file{~/.gitconfig}.

We provide some default settings in @file{etc/git/gitconfig} which modify
how patches are generated, making them easier to read and apply.  These
settings can be applied by manually copying them to @file{.git/config} in
your checkout, or by telling Git to include the whole file:

@example
git config --local include.path ../etc/git/gitconfig
@end example

From then on, any changes to @file{etc/git/gitconfig} would automatically
take effect.

Since the first patch in a series must be sent separately (@pxref{Отправка пакета исправлений}), it can also be helpful to tell @command{git format-patch} to
handle the e-mail threading instead of @command{git send-email}:

@example
git config --local format.thread shallow
git config --local sendemail.thread no
@end example

@node Отправка пакета исправлений
@subsection Отправка пакета исправлений
@cindex группы патчей
@cindex @code{git send-email}
@cindex @code{git format-patch}

@unnumberedsubsubsec Single Patches
@anchor{Single Patches}
The @command{git send-email} command is the best way to send both single
patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
list.  Sending patches as email attachments may make them difficult to
review in some mail clients, and @command{git diff} does not store commit
metadata.

@quotation Примечание
The @command{git send-email} command is provided by the @code{send-email}
output of the @code{git} package, i.e. @code{git:send-email}.
@end quotation

The following command will create a patch email from the latest commit, open
it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to the Guix
mailing list to be reviewed and merged:

@example
$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
@end example

@quotation Tip
To add a prefix to the subject of your patch, you may use the
@option{--subject-prefix} option.  The Guix project uses this to specify
that the patch is intended for a branch or repository other than the
@code{master} branch of @url{https://git.savannah.gnu.org/cgit/guix.git}.

@example
git send-email -1 -a --base=auto \
    --subject-prefix='PATCH core-updates' \
    --to=guix-patches@@gnu.org
@end example
@end quotation

The patch email contains a three-dash separator line after the commit
message.  You may ``annotate'' the patch with explanatory text by adding it
under this line.  If you do not wish to annotate the email, you may drop the
@option{-a} flag (which is short for @option{--annotate}).

The @option{--base=auto} flag automatically adds a note at the bottom of the
patch of the commit it was based on, making it easier for maintainers to
rebase and merge your patch.

If you need to send a revised patch, don't resend it like this or send a
``fix'' patch to be applied on top of the last one; instead, use
@command{git commit -a} or @url{https://git-rebase.io, @command{git rebase}}
to modify the commit, and use the
@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} flag
with @command{git send-email}.

@example
$ git commit -a
$ git send-email -1 -a --base=auto -v @var{REVISION} \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
@end example

You can find out @var{ISSUE_NUMBER} either by searching on the mumi
interface at @url{issues.guix.gnu.org} for the name of your patch or reading
the acknowledgement email sent automatically by Debbugs in reply to incoming
bugs and patches, which contains the bug number.

@unnumberedsubsubsec Notifying Teams
@anchor{Notifying Teams}
@cindex teams
The @file{etc/teams.scm} script may be used to notify all those who may be
interested in your patch of its existence (@pxref{Teams}).  Use
@command{etc/teams.scm list-teams} to display all the teams, decide which
team(s) your patch relates to, and use @command{etc/teams.scm cc} to output
various @command{git send-email} flags which will notify the appropriate
team members, or use @command{etc/teams.scm cc-members} to detect the
appropriate teams automatically.

@unnumberedsubsubsec Multiple Patches
@anchor{Multiple Patches}
@cindex cover letter
While @command{git send-email} alone will suffice for a single patch, an
unfortunate flaw in Debbugs means you need to be more careful when sending
multiple patches: if you send them all to the @email{guix-patches@@gnu.org}
address, a new issue will be created for each patch!

When sending a series of patches, it's best to send a Git ``cover letter''
first, to give reviewers an overview of the patch series.  We can create a
directory called @file{outgoing} containing both our patch series and a
cover letter called @file{0000-cover-letter.patch} with @command{git
format-patch}.

@example
$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
      --cover-letter --base=auto
@end example

We can now send @emph{just} the cover letter to the
@email{guix-patches@@gnu.org} address, which will create an issue that we
can send the rest of the patches to.

@example
$ git send-email outgoing/0000-cover-letter.patch -a \
      --to=guix-patches@@debbugs.gnu.org \
      $(etc/teams.scm cc-members ...)
$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
@end example

Ensure you edit the email to add an appropriate subject line and blurb
before sending it.  Note the automatically generated shortlog and diffstat
below the blurb.

Once the Debbugs mailer has replied to your cover letter email, you can send
the actual patches to the newly-created issue address.

@example
$ git send-email outgoing/*.patch \
      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
      $(etc/teams.scm cc-members ...)
$ rm -rf outgoing # we don't need these anymore
@end example

Thankfully, this @command{git format-patch} dance is not necessary to send
an amended patch series, since an issue already exists for the patchset.

@example
$ git send-email -@var{NUMBER_COMMITS} \
      -v@var{REVISION} --base=auto \
      --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
@end example

If need be, you may use @option{--cover-letter -a} to send another cover
letter, e.g. for explaining what's changed since the last revision, and
these changes are necessary.

@node Teams
@subsection Teams
@cindex teams

There are several teams mentoring different parts of the Guix source code.
To list all those teams, you can run from a Guix checkout:

@example
$ ./etc/teams.scm list-teams
id: mentors
name: Mentors
description: A group of mentors who chaperone contributions by newcomers.
members:
+ Christopher Baines <mail@@cbaines.net>
+ Ricardo Wurmus <rekado@@elephly.net>
+ Mathieu Othacehe <othacehe@@gnu.org>
+ jgart <jgart@@dismail.de>
+ Ludovic Courtès <ludo@@gnu.org>
@dots{}
@end example

You can run the following command to have the @code{Mentors} team put in CC
of a patch series:

@example
$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
@end example

The appropriate team or teams can also be inferred from the modified files.
For instance, if you want to send the two latest commits of the current Git
repository to review, you can run:

@example
$ guix shell -D guix
[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
@end example

@node Отслеживание ошибок и патчей
@section Отслеживание ошибок и патчей

This section describes how the Guix project tracks its bug reports and patch
submissions.

@menu
* The Issue Tracker::        The official bug and patch tracker.
* Debbugs User Interfaces::  Ways to interact with Debbugs.
* Debbugs Usertags::         Tag reports with custom labels.
@end menu

@node The Issue Tracker
@subsection The Issue Tracker

@cindex сообщения об ошибке, отслеживание
@cindex отправка патча, отслеживание
@cindex отслеживание заявок об ошибках
@cindex Debbugs, система отслеживания ошибок
Отчёты об ошибках и предложенные исправления сейчас отслеживаются с помощью
Debbugs на веб-сайте @uref{https://bugs.gnu.org}. Отчёты об ошибках,
относящиеся к пакету @code{guix} (на языке Debbugs), отправляйте по адресу
@email{bug-guix@@gnu.org}, а предлагаемые исправления для пакета
@code{guix-patches} — по адресу @email{guix-patches@@gnu.org}
(@pxref{Отправка исправлений}).

@node Debbugs User Interfaces
@subsection Debbugs User Interfaces

Для просмотра вопросов доступен веб-интерфейс (на самом деле даже @emph{два}
веб-интерфейса):

@itemize
@item
@url{https://issues.guix.gnu.org} предоставляет приятный
интерфейс@footnote{Веб-интерфейс по адресу @url{https://issues.guix.gnu.org}
работает на Mumi, прятном примере програмного обеспечения, написанного на
Guile, и вы можете помочь!
См.@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} чтобы
просматривать отчеты об ошибках и исправлениях, а также участвовать в
обсуждениях;
@item
@url{https://gnupg.org/, GNU libgcrypt} списки отчётов об ошибках;
@item
@url{https://bugs.gnu.org/guix-patches} списки патчей на рассмотрении.
@end itemize

Чтобы просмотреть обсуждения, связанные с номером проблемы @var{n},
перейдите на @indicateurl{https://issues.guix.gnu.org/@var{n}} или
@indicateurl{https://bugs.gnu.org/@var{n}}.

Если вы используете Emacs, вам может быть удобнее взаимодействовать с
проблемами при помощи @file{debbugs.el}, который вы можете установить с
помощью:

@example
guix install emacs-debbugs
@end example

Например, чтбы уввидеть все открытые заявки на @code{guix-patches}, введите:

@example
@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
@end example

@xref{Top,,, debbugs-ug, Debbugs User Guide} для подробной информации об
этом полезном инструменте!

@node Debbugs Usertags
@subsection Debbugs Usertags

@cindex usertags, for debbugs
@cindex Debbugs usertags
Debbugs provides a feature called @dfn{usertags} that allows any user to tag
any bug with an arbitrary label.  Bugs can be searched by usertag, so this
is a handy way to organize bugs@footnote{The list of usertags is public
information, and anyone can modify any user's list of usertags, so keep that
in mind if you choose to use this feature.}.

For example, to view all the bug reports (or patches, in the case of
@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux} for
the user @code{guix}, open a URL like the following in a web browser:
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.

For more information on how to use usertags, please refer to the
documentation for Debbugs or the documentation for whatever tool you use to
interact with Debbugs.

In Guix, we are experimenting with usertags to keep track of
architecture-specific issues.  To facilitate collaboration, all our usertags
are associated with the single user @code{guix}.  The following usertags
currently exist for that user:

@table @code

@item aarch64-linux
The purpose of this usertag is to make it easy to find the issues that
matter most for the @code{powerpc64le-linux} system type.  Please assign
this usertag to bugs or patches that affect @code{powerpc64le-linux} but not
other system types.  In addition, you may use it to identify issues that for
some reason are particularly important for the @code{powerpc64le-linux}
system type, even if the issue affects other system types, too.

@item воспроизводимость
For issues related to reproducibility.  For example, it would be appropriate
to assign this usertag to a bug report for a package that fails to build
reproducibly.

@end table

If you're a committer and you want to add a usertag, just start using it
with the @code{guix} user.  If the usertag proves useful to you, consider
updating this section of the manual so that others will know what your
usertag means.

@node Доступ к коммитам
@section Доступ к коммитам

@cindex доступ для отправки коммитов, для разработчиков
Everyone can contribute to Guix without having commit access
(@pxref{Отправка исправлений}).  However, for frequent contributors, having
write access to the repository can be convenient.  As a rule of thumb, a
contributor should have accumulated fifty (50) reviewed commits to be
considered as a committer and have sustained their activity in the project
for at least 6 months.  This ensures enough interactions with the
contributor, which is essential for mentoring and assessing whether they are
ready to become a committer.  Commit access should not be thought of as a
``badge of honor'' but rather as a responsibility a contributor is willing
to take to help the project.

The following sections explain how to get commit access, how to be ready to
push commits, and the policies and community expectations for commits pushed
upstream.

@subsection Applying for Commit Access

When you deem it necessary, consider applying for commit access by following
these steps:

@enumerate
@item
Найдите трех коммиттеров, которые поручаются за вас. Вы можете просмотреть
список коммиттеров по адресу
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Каждый из
них должен отправить заявление по электронной почте на адрес
@email{guix-maintainers@@gnu.org} (личный псевдоним коллектива
сопровождающих), подписанный ключом OpenPGP.

Ожидается, что коммиттеры взаимодействовали с вами как c участником и могли
судить, достаточно ли вы знакомы с проектом. Это @emph{не} суждение о
ценности вашей работы, поэтому отказ следует скорее интерпретировать как
«давайте попробуем позже».

@item
Отправьте @email{guix-keepers@@gnu.org} сообщение с указанием ваших
намерений, перечисляя трех коммиттеров, поддерживающих вашу заявку,
подписанных ключом OpenPGP, который вы будете использовать для подписания
коммитов, и указав свой отпечаток (смотри ниже). Ознакомся с
@uref{https://emailselfdefense.fsf.org/ru/}, чтобы познакомиться с
криптографией с открытым ключом с помощью GnuPG.

@c See <https://sha-mbles.github.io/>.
Настройте GnuPG так, чтобы он никогда не использовал хэш-алгоритм SHA1 для
цифровых подписей, который, как известно, небезопасен с 2019 года. Например,
добавив следующую строку в @file{~/.gnupg/gpg.conf} (@pxref{GPG Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Маинтайнеры решают, предоставлять ли вам доступ к коммитам, обычно следуя
рекомендациям ваших рефералов.

@item
@cindex Коммиты, подписанные OpenPGP
Получив доступ, пожалуйста, отправьте сообщение на адрес
@email{guix-devel@@gnu.org}, чтобы снова подписать его ключом OpenPGP,
который вы будете использовать для подписания коммитов (сделайте это перед
отправкой первого коммита). Таким образом, каждый может заметить и
убедиться, что это ваш ключ OpenPGP.

@quotation Важно
Перед тем, как вы отправите изменения впервые, сопровождающие должны:

@enumerate
@item
добавить ваш OpenPGP ключ в @code{keyring} ветку;
@item
добавьте отпечаток вашего OpenPGP ключа в @file{.guix-authorizations} файл
ветки (-ок), которые вы подпишите (commit).
@end enumerate
@end quotation

@item
Обязательно прочтите остальную часть этого раздела!
@end enumerate

@quotation Примечание
Маинтейнеры с радостью предоставят доступ к коммитам людям, которые внесли
свой вклад в течение некоторого времени и имеют послужной список - не
стесняйтесь и не недооценивайте свою работу!

Тем не менее, обратите внимание, что проект работает над созданием более
автоматизированной системы проверки и объединения исправлений, что, как
следствие, может привести к тому, что у нас будет меньше людей, имеющих
доступ к главному репозиторию. Будьте на связи!
@end quotation

Все коммиты, которые передаются в центральный репозиторий в Саванне, должны
быть подписаны ключом OpenPGP, а открытый ключ должен быть загружен в вашу
учетную запись пользователя на Саванне и на серверы открытых ключей, такие
как @code{keys.openpgp.org}. Чтобы настроить Git для автоматической подписи
коммитов, запустите:

@example
git config commit.gpgsign true

# Substitute the fingerprint of your public PGP key.
git config user.signingkey CABBA6EA1DC0FF33
@end example

To check that commits are signed with correct key, use:

@example
make authenticate
@end example

You can prevent yourself from accidentally pushing unsigned or signed with
the wrong key commits to Savannah by using the pre-push Git hook located at
@file{etc/git/pre-push}:

@example
cp etc/git/pre-push .git/hooks/pre-push
@end example

It additionally calls @code{make check-channel-news} to be sure
@file{news.scm} file is correct.

@subsection Commit Policy

Если вы получили доступ к коммиту, пожалуйста, следуйте приведенной ниже
политике (обсуждение политики может проходить по адресу
@email{guix-devel@@gnu.org}).

Нетривиальные патчи всегда должны публиковаться на
@email{guix-patches@@gnu.org} (тривиальные патчи включают исправление
опечаток и т.д.). Этот список рассылки заполняет базу данных отслеживания
патчей (@pxref{Отслеживание ошибок и патчей}).

Для патчей, которые просто добавляют новый пакет или внсит небольшие
изменения считается нормальным отправить коммит, если вы уверены (что
означает, что вы успешно встроили его в настройку chroot и провели разумный
аудит авторских прав и лицензий). Аналогично для обновлений пакетов, за
исключением обновлений, которые вызывают много перестроений (например,
обновление GnuTLS или GLib). У нас есть список рассылки для уведомлений о
коммитах (@email{guix-commits@@gnu.org}), так что люди могут это
заметить. Перед отправкой изменений обязательно запустите @code{git pull
--rebase}.

Когда вы отправляете коммит от имени кого-то другого, добавьте строку
@code{Signed-off-by} в конце сообщения коммит лога---например, с
@command{git am --signoff}. Это улучшает отслеживание того, кто что сделал.

При добавлении новостей канала (@pxref{Каналы, Writing Channel News}),
убедитесь, что они правильно сформированы, выполнив следующую команду прямо
перед нажатием:

@example
make check-channel-news
@end example

Для чего-либо еще, пожалуйста, отправьте сообщение на
@email{guix-patches@@gnu.org} и оставьте время для обзора, ничего не коммитя
(@pxref{Отправка исправлений}). Если вы не получили никакого ответа через две
недели, и если вы уверены, что все в порядке, будь нормальным совершить
коммит.

Эта последняя часть подлежит корректировке, что позволяет отдельным лицам
вносить непосредственные изменения в не противоречивые изменения в тех
частях, с которыми они знакомы.

@subsection Addressing Issues

Peer review (@pxref{Отправка исправлений}) and tools such as @command{guix
lint} (@pxref{Запуск guix lint}) and the test suite (@pxref{Запуск набора тестов}) should catch issues before they are pushed.  Yet, commits that
``break'' functionality might occasionally go through.  When that happens,
there are two priorities: mitigating the impact, and understanding what
happened to reduce the chance of similar incidents in the future.  The
responsibility for both these things primarily lies with those involved, but
like everything this is a group effort.

Some issues can directly affect all users---for instance because they make
@command{guix pull} fail or break core functionality, because they break
major packages (at build time or run time), or because they introduce known
security vulnerabilities.

@cindex reverting commits
The people involved in authoring, reviewing, and pushing such commit(s)
should be at the forefront to mitigate their impact in a timely fashion: by
pushing a followup commit to fix it (if possible), or by reverting it to
leave time to come up with a proper fix, and by communicating with other
developers about the problem.

If these persons are unavailable to address the issue in time, other
committers are entitled to revert the commit(s), explaining in the commit
log and on the mailing list what the problem was, with the goal of leaving
time to the original committer, reviewer(s), and author(s)  to propose a way
forward.

Once the problem has been dealt with, it is the responsibility of those
involved to make sure the situation is understood.  If you are working to
understand what happened, focus on gathering information and avoid assigning
any blame.  Do ask those involved to describe what happened, do not ask them
to explain the situation---this would implicitly blame them, which is
unhelpful.  Accountability comes from a consensus about the problem,
learning from it and improving processes so that it's less likely to
reoccur.

@subsection Commit Revocation

Чтобы уменьшить вероятность ошибок, учетные записи контрибьюторов будут
удалены из проекта Guix на Savannah, а их ключи - из
@file{.guix-authorizations} после 12 месяцев бездействия; они могут
попросить восстановить доступ к отправке коммитов, отправив электронное
письмо мэйнтейнеров, не проходя через процесс подтверждения.

Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
current list of maintainers.  You can email them privately at
@email{guix-maintainers@@gnu.org}.} may also revoke an individual's commit
rights, as a last resort, if cooperation with the rest of the community has
caused too much friction---even within the bounds of the project's code of
conduct (@pxref{Содействие}).  They would only do so after public or
private discussion with the individual and a clear notice.  Examples of
behavior that hinders cooperation and could lead to such a decision include:

@itemize
@item repeated violation of the commit policy stated above;
@item repeated failure to take peer criticism into account;
@item breaching trust through a series of grave incidents.
@end itemize

When maintainers resort to such a decision, they notify developers on
@email{guix-devel@@gnu.org}; inquiries may be sent to
@email{guix-maintainers@@gnu.org}.  Depending on the situation, the
individual may still be welcome to contribute.

@subsection Helping Out

И последнее: проект продолжает двигаться вперед, потому что коммиттеры не
только вносят свои собственные потрясающие изменения, но также уделяют свое
время на @emph{reviewing} и продвижение изменений других людей. Как
коммиттер, вы можете использовать свой опыт и передавать права, чтобы помочь
и другим участникам!

@node Обновление пакета Guix
@section Обновление пакета Guix

@cindex guix package: (guix)Запуск guix package
Иногда желательно обновить сам пакет @code{guix} (пакет определен в
@code{(gnu packages package-management)}), например, чтобы сделать новые
функции демона доступными для использования сервисом
@code{guix-service-type}.  Чтобы упростить эту задачу, можно использовать
следующую команду:

@example
make authenticate
@end example

@code{update-guix-package} make target воспользуется последним известным
коммитом, согласно @code{HEAD} вашего Guix checkout, вычислить хэш
источников Guix, соответствующих этому коммиту и обновите @code{commit},
@code{revision} и хэш @code{guix}.

Чтобы убедиться, что обновленные хеш-суммы пакета @code{guix} верны и что он
может быть успешно собран, следующая команда может быть запущена из каталога
Guix (from the directory of your Guix checkout):

@example
./pre-inst-env guix build gnew --keep-failed
@end example

Чтобы предотвратить случайное обновление пакета @code{guix} к коммиту, на
которую другие не могут ссылаться, выполняется проверка того, что
использованный коммит уже был отправлен в репозиторий Guix, размещенный в
Savannah.

Эту проверку можно отключить @emph{на свой страх и риск}, установив
переменну окружения @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT}.  Когда эта
переменная установлена, обновленный исходник пакета также добавляется в
хранилище.  Это часть процесса выпуска Guix.

@cindex документация
@node Writing Documentation
@section Writing Documentation

Guix is documented using the Texinfo system.  If you are not yet familiar
with it, we accept contributions for documentation in most formats.  That
includes plain text, Markdown, Org, etc.

Documentation contributions can be sent to @email{guix-patches@@gnu.org}.
Prepend @samp{[DOCUMENTATION]} to the subject.

When you need to make more than a simple addition to the documentation, we
prefer that you send a proper patch as opposed to sending an email as
described above.  @xref{Отправка исправлений} for more information on how to
send your patches.

To modify the documentation, you need to edit @file{doc/guix.texi} and
@file{doc/contributing.texi} (which contains this documentation section), or
@file{doc/guix-cookbook.texi} for the cookbook.  If you compiled the Guix
repository before, you will have many more @file{.texi} files that are
translations of these documents.  Do not modify them, the translation is
managed through @uref{https://translate.fedoraproject.org/projects/guix,
Weblate}.  @xref{Тестирование Guix.} for more information.

To render documentation, you must first make sure that you ran
@command{./configure} in your source tree (@pxref{Запуск Guix перед его установкой}).  After that you can run one of the following commands:

@itemize
@item @samp{make doc/guix.info} to compile the Info manual.
      You can check it with @command{info doc/guix.info}.
@item @samp{make doc/guix.html} to compile the HTML version.
      You can point your browser to the relevant file in the @file{doc/guix.html}
directory.
@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
@end itemize

@cindex транзакции
@cindex l10n
@cindex i18n
@cindex Работа с языками, поддерживаемыми gcc.
@node Тестирование Guix.
@section Тестирование Guix.

Написание кода и пакетов - не единственный способ внести значимый вклад в
Guix.  Перевод на язык, на котором вы говорите---еще один пример вашего
ценного вклада.  Этот раздел предназначен для описания процесса
перевода. Здесь представлены советы о том, как вы можете принять участие,
что можно перевести, каких ошибок следует избегать и что мы можем сделать,
чтобы вам помочь!

Guix - это большой проект, состоящий из нескольких компонентов, которые
можно перевести.  Мы координируем работу по переводу на
@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance},
размещенном нашими друзьями в Fedora.  Для отправки переводов вам
потребуется учетная запись.

Некоторое программное обеспечение, упакованное в Guix, также содержит
переводы.  Мы не хостим для них платформу для перевода.  Если вы хотите
перевести пакет, предоставленный Guix, вам следует связаться с их
разработчиками или найти информацию на их веб-сайтах.  Например, вы можете
найти домашнюю страницу пакета @code{hello}, набрав @code{guix show
hello}. В строке ``домашняя страница'' вы увидите
@url{https://www.gnu.org/software/hello/} в качестве домашней страницы.

Многие пакеты GNU и не-GNU можно перевести на @uref{https:
//translationproject.org,Translation Project}.  Некоторые проекты с
несколькими компонентами имеют собственную платформу.  Например, GNOME имеет
собственную платформу @uref{https://l10n.gnome.org/,Damned Lies}.

Guix состоит из пяти компонентов, размещенных на Weblate.

@itemize
@item @code{guix} содержит все строки из программного обеспечения Guix (
      установщик системы, менеджер пакетов и т.д.), за исключением пакетов.
@item @code{packages} содержит синопсис (описание пакета из одного предложения
      ) и (более подробное) описание пакетов в Guix.
@item @code{website} содержит официальный сайт Guix, за исключением
      сообщения в блогах и мультимедийный контент.
@item @code{documentation-manual} соответствует этому руководству.
@item @code{documentation-cookbook} - компонент для поваренной книги.
@end itemize

@subsubheading поколения

После создания учетной записи вы сможете выбрать компонент из
@uref{https://translate.fedoraproject.org/projects/guix/,the guix project} и
выбрать язык.  Если вашего языка нет в списке, пройдите вниз и нажмите
кнопку ``Начать новый перевод''.  Выберите из списка язык, на который вы
хотите перевести, чтобы начать новый перевод.

Как и многие другие бесплатные программные пакеты, Guix использует
@uref{https://www.gnu.org/software/gettext,GNU Gettext} для своих переводов,
с помощью которых переводимые строки извлекаются из исходного кода в так
называемые PO-файлы.

Несмотря на то, что файлы PO являются текстовыми файлами, изменения следует
вносить не с помощью текстового редактора, а с помощью программного
обеспечения для редактирования PO.  Weblate интегрирует функции
редактирования PO.  В качестве альтернативы переводчики могут использовать
любой из различных бесплатных программных инструментов для заполнения
переводов, одним из примеров которых является
@uref{https://poedit.net/,Poedit} и (после входа в систему)
@uref{https://docs.weblate.org/en/latest/user/files.html, загрузить}
измененный файл.  Существует также специальный @uref
{https://www.emacswiki.org/emacs/PoMode,PO режим редактирования} для
пользователей GNU Emacs.  Со временем переводчики узнают, какое программное
обеспечение им нравится и какие функции им нужны.

На Weblate вы найдете различные ссылки на редактор, который покажет
различные подмножества (или все) строк (-и).  Посмотрите вокруг и на
@uref{https://docs.weblate.org/en/latest/,documentation}, чтобы ознакомиться
с платформой.

@subsubheading Компоненты перевода

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

@table @asis
@item guix
Guix is written in the Guile programming language, and some strings contain
special formatting that is interpreted by Guile.  These special formatting
should be highlighted by Weblate.  They start with @code{~} followed by one
or more characters.

When printing the string, Guile replaces the special formatting symbols with
actual values.  For instance, the string @samp{ambiguous package
specification `~a'} would be substituted to contain said package
specification instead of @code{~a}.  To properly translate this string, you
must keep the formatting code in your translation, although you can place it
where it makes sense in your language.  For instance, the French translation
says @samp{spécification du paquet « ~a » ambiguë} because the adjective
needs to be placed in the end of the sentence.

If there are multiple formatting symbols, make sure to respect the order.
Guile does not know in which order you intended the string to be read, so it
will substitute the symbols in the same order as the English sentence.

As an example, you cannot translate @samp{package '~a' has been superseded
by '~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would
be reversed.  If @var{foo} is superseded by @var{bar}, the translation would
read @samp{'foo' superseeds package 'bar'}.  To work around this problem, it
is possible to use more advanced formatting to select a given piece of data,
instead of following the default English order.  @xref{Formatted Output,,,
guile, GNU Guile Reference Manual}, for more information on formatting in
Guile.

@item пакеты

Описания пакетов иногда содержат разметку Texinfo (@pxref{Краткие обзоры и описания}).  Разметка Texinfo выглядит как @samp{@@code@{rm -rf@}},
@samp{@@emph@{important@}} и т.д.  При переводе оставляйте разметку как
есть.

The characters after ``@@'' form the name of the markup, and the text
between ``@{'' and ``@}'' is its content.  In general, you should not
translate the content of markup like @code{@@code}, as it contains literal
code that do not change with language.  You can translate the content of
formatting markup such as @code{@@emph}, @code{@@i}, @code{@@itemize},
@code{@@item}.  However, do not translate the name of the markup, or it will
not be recognized.  Do not translate the word after @code{@@end}, it is the
name of the markup that is closed at this position (e.g.@: @code{@@itemize
... @@end itemize}).

@item documentation-manual and documentation-cookbook

Первый шаг к успешному переводу руководства---найти и перевести следующие
строки @emph{первыми}:

@itemize
@item @code{version.texi}: переведите эту строку как @code{version-xx.texi},
      где @code{xx}---код вашего языка (тот, который показан в URL-адресе на
weblate).
@item @code{contributing.texi}: переведите эту строку как
      @code{contributing.xx.texi}, где @code {xx} - код того же языка.
@item @code{Top}: Не переводите эту строку, это важно для Texinfo.
      Если вы переведете его, документ будет пустым (missing a Top node).  Найдите
его и зарегистрируйте @code{Top} в качестве его перевода.
@end itemize

Перевод этих строк гарантирует, что мы сможем включить ваш перевод в
репозиторий guix, не нарушая процесс make или механизм @command{guix pull}.

The manual and the cookbook both use Texinfo.  As for @code{packages},
please keep Texinfo markup as is.  There are more possible markup types in
the manual than in the package descriptions.  In general, do not translate
the content of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value},
etc.  You should translate the content of formatting markup such as
@code{@@emph}, @code{@@i}, etc.

The manual contains sections that can be referred to by name by
@code{@@ref}, @code{@@xref} and @code{@@pxref}.  We have a mechanism in
place so you do not have to translate their content.  If you keep the
English title, we will automatically replace it with your translation of
that title.  This ensures that Texinfo will always be able to find the
node. If you decide to change the translation of the title, the references
will automatically be updated and you will not have to update them all
yourself.

При переводе ссылок из cookbook в мануал нужно заменить название мануала и
название раздела.  Например, чтобы перевести @code{@@pxref@{Defining
Packages,,, guix, GNU Guix Reference Manual@}}, вы должны
заменить@code{Defining Packages} заголовком этого раздела в переведенном
руководстве @emph{только} если это название переведено.  Если название еще
не переведено на ваш язык, не переводите его здесь, иначе ссылка будет
неработающей.  Замените @code{guix} на @code{guix.xx}, где @code{xx} - код
вашего языка.  @code{GNU Guix Reference Manual}---это текст ссылки.  Вы
можете перевести его как хотите.

@item официальный веб-сайт

Страницы веб-сайта написаны с использованием SXML, версии HTML (основного
языка Интернета) с s-выражениями.  У нас есть процесс извлечения переводимых
строк из источника и замены сложных s-выражений на более знакомую разметку
XML, где каждая разметка пронумерована.  Переводчики могут произвольно
изменять порядок, как в следующем примере.

@example
#. TRANSLATORS: Defining Packages is a section name
#. in the English (en) manual.
#: apps/base/templates/about.scm:64
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
@end example

Обратите внимание, что вам нужно включить такие же разметки.  Вы не можете
ничего пропустить.
@end table

Если вы допустили ошибку, компонент может не работать должным образом с
вашим языком или даже привести к сбою guix pull.  Чтобы предотвратить это, у
нас есть процесс проверки содержимого файлов перед отправкой в наш
репозиторий.  Если, мы не сможем обновить перевод для вашего языка в Guix,
мы уведомим вас (через веб-сайт и/или по электронной почте), чтобы решить
проблему.

@subsubheading Вне Weblate

В настоящее время некоторые части Guix не могут быть переведены на
Weblate---требуется помощь!

@itemize
@item @command{guix pull} новости можно перевести в @file{news.scm}, но не
      available from Weblate.  If you want to provide a translation, you can
prepare a patch as described above, or simply send us your translation with
the name of the news entry you translated and your language. @xref{Написание новостей канала}, for more information about channel news.
@item Guix blog posts cannot currently be translated.
@item The installer script (for foreign distributions) is entirely in English.
@item Some of the libraries Guix uses cannot be translated or are translated
      outside of the Guix project.  Guile itself is not internationalized.
@item Other manuals linked from this manual or the cookbook might not be
      транзакции
@end itemize

@subsubheading Conditions for Inclusion

There are no conditions for adding new translations of the @code{guix} and
@code{guix-packages} components, other than they need at least one
translated string.  New languages will be added to Guix as soon as
possible.  The files may be removed if they fall out of sync and have no
more translated strings.

Given that the web site is dedicated to new users, we want its translation
to be as complete as possible before we include it in the language menu.
For a new language to be included, it needs to reach at least 80%
completion.  When a language is included, it may be removed in the future if
it stays out of sync and falls below 60% completion.

The manual and cookbook are automatically added in the default compilation
target.  Every time we synchronize translations, developers need to
recompile all the translated manuals and cookbooks.  This is useless for
what is essentially the English manual or cookbook.  Therefore, we will only
include a new language when it reaches 10% completion in the component.
When a language is included, it may be removed in the future if it stays out
of sync and falls below 5% completion.

@subsubheading Translation Infrastructure

Weblate is backed by a git repository from which it discovers new strings to
translate and pushes new and updated translations.  Normally, it would be
enough to give it commit access to our repositories.  However, we decided to
use a separate repository for two reasons.  First, we would have to give
Weblate commit access and authorize its signing key, but we do not trust it
in the same way we trust guix developers, especially since we do not manage
the instance ourselves.  Second, if translators mess something up, it can
break the generation of the website and/or guix pull for all our users,
independently of their language.

For these reasons, we use a dedicated repository to host translations, and
we synchronize it with our guix and artworks repositories after checking no
issue was introduced in the translation.

Developers can download the latest PO files from weblate in the Guix
repository by running the @command{make download-po} command.  It will
automatically download the latest files from weblate, reformat them to a
canonical form, and check they do not contain issues.  The manual needs to
be built again to check for additional issues that might crash Texinfo.

Before pushing new translation files, developers should add them to the make
machinery so the translations are actually available.  The process differs
for the various components.

@itemize
@item New po files for the @code{guix} and @code{packages} components must
      be registered by adding the new language to @file{po/guix/LINGUAS} or
@file{po/packages/LINGUAS}.
@item New po files for the @code{documentation-manual} component must be
      registered by adding the file name to @code{DOC_PO_FILES} in
@file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
@code{info_TEXINFOS} in @file{doc/local.mk} and the generated
@file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
@code{TRANSLATED_INFO} also in @file{doc/local.mk}.
@item New po files for the @code{documentation-cookbook} component must be
      registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
@file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
@file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also in
@file{doc/local.mk}.
@item New po files for the @code{website} component must be added to the
      @code{guix-artwork} repository, in @file{website/po/}.
@file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must be
updated accordingly (see @file{website/i18n-howto.txt} for more information
on the process).
@end itemize
