20.6 Отправка исправлений

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 git format-patch sent to the guix-patches@gnu.org mailing list (see Submitting patches to a project in Git User Manual). Contributors are encouraged to take a moment to set some Git repository options (see Конфигурирование Git) first, which can improve the readability of patches. Seasoned Guix developers may also want to look at the section on commit access (see Доступ к коммитам).

Для данной рассылки создаются резервные копии с помощью Debbugs, что позволяет нам отслеживать присылаемые патчи (see Отслеживание ошибок и патчей). Каждому сообщению, отправленному в эту рассылку, присваивается новый номер трекинга. Затем пользователи могут общаться относительно конкретного патча, отправляя электронные письма на адрес NNN@debbugs.gnu.org, где NNN — это номер трекинга (see Отправка пакета исправлений).

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

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

1. When generating your patches with git format-patch or git send-email, we recommend using the option --base=, perhaps with the value auto. This option adds a note to the patch stating which commit the patch is based on. This helps reviewers understand how to apply and review your patches.
2. Если авторы пакета программного обеспечения преоставляют криптографическую подпись для архива релиза, выполните проверку аутентичности архива. Для отдельного файла GPG-подписи это можно сделать командой gpg --verify.
3. Потратьте немного времени, чтобы предоставить адекватное краткое описание и полное описание пакета. Смотрите See Краткие обзоры и описания для подробностей.
4. Запустите guix lint package, где package - это имя нового изменённого пакета, и устраните любые ошибки из отчёта (see Запуск guix lint).
5. Run guix style package to format the new package definition according to the project’s conventions (see Invoking guix style).
6. Убедитесь, что пакет собирается на вашей платформе, используя guix build package.
7. 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 qemu-binfmt-service-type to emulate them. In order to enable it, add the virtualization service module and the following service to the list of services in your operating-system configuration:

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

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

   Также можно собирать пакеты под различные платформы, обозначив опцию --system. Например, чтобы собрать пакет "hello" для архитектур armhf, aarch64, или mips64 вы должны выполнить соответственно следующее:

   "guix build --system=armhf-linux --rounds=2 hello
   "guix build --system=aarch64-linux --rounds=2 hello
   

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

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

9. Просмотрите отчеты guix size (see Запуск guix size). Это позволит найти связь с другими пакетами, сохранившуюся без необходимости. Это также позволяет решить, как разделить пакет (see Пакеты со множественным выходом) и какие должны использоваться опциональные зависимости. В частности, это способ избежать использование большого texlive как зависимости и использовать texlive-tiny или texlive-union вместо него.
10. For important changes, check that dependent packages (if applicable) are not affected by the change; guix refresh --list-dependent package will help you do that (see Запуск guix refresh).

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

    300 пакетов зависимостей или менее

    бренч master (не разрушающие изменения).

    от 300 до 1200 пакетов зависимостей

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

    более 1200 пакетов зависимостей

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

    All these branches are tracked by our build farm and merged into 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.

    Когда мы решим начать сборку веток staging или core-updates, они будут форкнуты (forked) и переименованы с суффиксом -frozen, после чего замороженные ветки будут получать только исправления ошибок. Ветки core-updates и staging остануться открыты для патчей в следующем цикле. Если вы не знаете, где разместить патч, спросите в списке рассылки или в IRC.

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

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

    guix build --rounds=2 my-package
    

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

    Другой способ — использовать guix challenge (see Запуск guix challenge). Можно запустить это один раз, когда коммит пакета был отправлен, и собрать с помощью ci.guix.gnu.org, чтобы проверить, что это даёт результат такой же, как у вас. Ещё лучше найти другую машину, на которой можно собрать это и выполнить guix publish. Так как другая удалённая машина дл сборки отличается от вашей, это может выявить проблемы, нарушающие детерминизм, связанные с аппаратным обеспечением, то есть вызванные использованием различных расширений ассемблера или другого ядра операционной системы, то есть касательно файлов uname или /proc.

12. При написании документации, пожалуйста, используйте нейтральную по гендеру лексику, когда речь идёт о людях, как например, тут singular "they", "their", "them" и т.д.
13. Проверьте, что ваш патч содержит изменения, связанные только с одной темой. Связывая вместе изменения, касающиеся различных тем, делает обзор сложным и медленным.

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

14. Please follow our code formatting rules, possibly running guix style script to do that automatically for you (see Форматирование кода).
15. Если это возможно, используйте зеркала при указании URL исходников (see Запуск guix download). Используйте надёжные URL’ы, а не сгенерированные. Например, архивы GitHub не являются идентичными между поколениями, так что в этом случае часто лучше клонировать репозиторий. Не используйте поле name в URL, это не очень удобно: если имя изменится, тогда URL будет неправильным.
16. Проверьте, собирается ли Guix (see Сборка из Git), и устраните предупреждения, особенно те, которые касаются использования неопределенных символов.
17. Убедитесь, что ваши изменения не ломают Guix и имитируйте guix pull вместе с:

    guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
    

Когда отправляете патч в рассылку, используйте ‘[PATCH] …’ в теме письма. Можно пользоваться почтовым клиентом или командой git send-email (see Отправка пакета исправлений). Мы предпочитаем получать патчи в виде простых текстовых сообщений внутри текста или отдельным вложением MIME. Рекомендуется уделять внимание вопросу, не изменяет ли почтовый клиент что-либо как символы новой строки или отступы, так как это потенциально может нарушить код патча.

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

Когда баг исправлен, пожалуйста, закройте тему, отправив сообщение на NNN-done@debbugs.gnu.org.