Загрузка и тестирование с помощью ubports-qa

`Сервис сборки UBports <https://ci.ubports.com> `_ может создавать пакеты Ubuntu Touch и размещать их в `репозитории UBports <https://repo.ubports.com> `_. Эта опция доступна любому разработчику, который желает ею воспользоваться.

В этом руководстве предполагается, что вы понимаете, как использовать Git и формировать запросы Pull Requests на GitHub.

Чтобы использовать UBports build service, изучите наше: doc:` соглашение об именах веток</about/process/branch-naming>`. Для правильной сборки пакета необходимо следовать соглашению для deb-пакетов для CI.

Создания форка репозитория

Первый шаг к внесению изменений в любой репозиторий, если нет прав на запись, - это сделать его копию. Откройте нужный репозиторий на GitHub и нажмите кнопку «Fork» в правом верхнем углу. Выберите нужную учетную запись и создайте копию (форк) репозитория на своем компьютере.

Теперь можно вносить любые правки!

Сделайте нужные правки и сохраните их

Теперь, когда доступен исходный код пакета, можно внести в него правки.

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

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

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

Обновите файл debian/changelog

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

Примечание

Это краткое описание формата debian/changelog. См. deb-changelog(5) для получения дополнительной информации.

Укажите номер новой версии

Для начала выясните номер текущей версии пакета:

head debian/changelog

Это покажет несколько строк, но первая для нас самая важная:

morph-browser (0.24+ubports2) xenial; urgency=medium

Словосочетание в круглых скобках ``(0.24+ubports2)` - это номер версии нашего пакета. Он состоит из нескольких частей:

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

Если Вы вносите большие изменения в репозиторий, а Ubuntu Touch находится в состоянии «upstream», то нужно увеличить первую часть номера версии до плюса (+) и сбросить дистрибуционный суффикс. В примере выше показано как будет выглядеть номер новой версии:

0.25+ubports0

Если вы вносите изменения только в сборку пакета (файлы в папке debian/“), лучше увеличивать только суффикс версии:

0.24+ubports3

Примечание

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

В журнале изменений - файле changelog - напишите о сделанных правках

Пришло время сделать запись в журнале изменений! Это можно сделать с помощью шаблона:

PACKAGE-NAME (VERSION) DISTRIBUTION; urgency=medium

  * CHANGES

-- NAME <EMAIL>  DATETIME

Если открыть файл debian/changelog, то можно увидеть, что каждая запись выполнена по этому формату. Такой формат помогает всем (включая компьютеры) читать и понимать содержимое файла. Это используется, например, для формирования правильного имени пакета при сборке новых версий.

Предположим, разработчик Джон Доу вносит изменения в пакет morph-browser для Ubuntu Touch. Он изменит поля, набранные заглавным шрифтом, следующим образом:

  • PACKAGE-NAME меняется на morph-browser

  • VERSION меняется на 0.24+ubports3 (как мы договорились выше по тексту)

  • DISTRIBUTION меняется на xenial

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

  • В поле NAME указывается имя разработчика. В данном случае - John Doe

  • В поле EMAIL указывается почтовый адрес разработчика, john.doe@example.com.

    Примечание

    Не следует использовать какой-то старый, или неактивный адрес электронной почты в качестве EMAIL для записей журнала изменений пакета.

  • В поле DATETIME указывается дата и время внесения записи в журнал изменений в формате RFC2822/RFC5322. Самый простой способ это сделать - запустить в терминале команду date -R.

Помните, что ни одна строка в одной записи журнала изменений не должна превышать 80 символов.

Далее можно посмотреть пример новой записи в журнале изменений:

morph-browser (0.24+ubports3) xenial; urgency=medium

  * Add the new "Hello world" script to the package. Fixes
    https://github.com/ubports/morph-browser/issues/404.
  * Fix whitespace and formatting in the format.qml file

-- John Doe <john.doe@example.com>  Mon, 29 Oct 2018 12:53:08 -0500

Добавьте новую запись в журнал изменений в верхнюю часть файла debian/changelog и нажмите на клавишу «Обновить журнал изменений». Это сохранит изменения. Теперь можно сделать Pull Request!

Создайте pull request

Pull request сигнализирует разработчикам UBports о правках кода, они проверят их и добавят в официальный репозиторий. Сейчас мы создадим такой запрос.

Откройте свой форк репозитория на GitHub. Перейдите к ветке, которую вы только выбрали клавишей «Branch»:

Using the branch selector on GitHub

Откройте нужную ветку, нажмите кнопку «New pull request», чтобы создать его. Вы попадете на страницу, где сможете просмотреть свои изменения и создать запрос pull request.

Дайте вашему запросу название и описание (включите ссылки на баг-репорты или другой материал). Убедитесь, что «базовая» ветвь - это та, к которой необходимо применить эти правки (скорее всего, это «xenial»), затем нажмите «Create pull request».

После создания pull request можно перейти к тестированию изменений с помощью службы сборки UBports!

Тестирование внесённых правок

Как только pull request создан (рядом с вашим последним коммитом появится зеленая галочка), можно протестировать свои изменения на мобильном устройстве.

Примечание

Если последний коммит помечен красным крестом, pull request не удалось выполнить. Щелкните на этот крестик, чтобы просмотреть журнал событий. Пока указанные там ошибки не будут устранены, ваш pull request не будет принят в работу.

Для установки сделанных правок мы будем использовать ubports-qa. Запишите идентификатор своего запроса (обозначен как #число после заголовка запроса) и выполните следующие действия:

  1. Убедитесь, что на мобильном устройстве установлена самая последняя версия Ubuntu Touch из канала devel.

  2. Получите доступ к оболочке вашего устройства. Инструкция Shell access via ADB or Shell access via SSH.

  3. Выполните команду``sudo ubports-qa install REPOSITORY PR``, вместо REPOSITORY нужно указать имя репозитория, для которого сформирован запрос PR, а PR - номером вашего запроса без символа #. . Например, выполните команду ``sudo ubports-qa morph-browser 123`, чтобы установить запрос PR 123 в репозиторий morph-browser.

ubports-qa автоматически добавит репозиторий, содержащий обновленный компонент, и начнет установку на устройство. Все, что нужно сделать, это проверить пакеты, которые предлагается установить, и нажать «да», если все корректно.

Если ubports-qa не может установить пакеты, запустите команду с флагом``-v`` (например, ubports-qa -v install ...). Если и это не помогло, отправьте весь лог-файл (начиная с символа $ перед командой ubports-qa) в Ubuntu Pastebin <https://paste.ubuntu.com/> `_ и свяжитесь с нами.

После того, как ubports-qa закончит работу, проверьте, действительно ли правки перенеслись в исходный текст проекта. Добавьте команду ubports-qa в свой pull request, а затем отправьте ссылку на pull request другим разработчикам и тестировщикам, чтобы они также могли протестировать изменения.

Получив обратную связь от тестировщиков, обязательно добавьте информацию в public request (или попросите их сделать это), чтобы все были в курсе состояния кода.

Каждый раз, когда вы вносите изменение и отправляете его на GitHub, запускается новая сборка. С помощью команды ``sudo ubports-qa update``можно получать самые свежие обновления системы.

Вот и всё!

Если вы и ваши тестировщики удовлетворены результатами работ по pull request, он будет переведён в статус «merged». После этого сборки системы станут доступны для всех пользователей Ubuntu Touch.

Спасибо за вклад в развитие операционной системы Ubuntu Touch!