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

The UBports build service is capable of building Ubuntu Touch packages and deploying them to the UBports repository. This capability is offered to any developer who wishes to take advantage of it.

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

To use the UBports build service, make sure you understand our branch naming convention. It is required that you follow the convention for deb-packages for CI to build your package correctly.

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

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

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

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

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

Before changing anything, make sure you have checked out the branch you want to work from (probably xenial, assuming you are making changes for the phone images). Then, create a new branch abiding by the branch naming convention.

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

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

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

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

Примечание

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

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

To start, figure out what the current version numbering for the package is:

head debian/changelog

This will return a few lines, but the first is the most important to us:

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

The part inside the parentheses (0.24+ubports2) is our version number. It consists of several parts:

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

If you are making large changes to the repository and UBports is the upstream, you should increment the first part of the version number before the plus (+) and reset the distribution suffix. In our example above, you would make this new version number:

0.25+ubports0

If you are making changes only to the package build (files in the debian/ folder), it is best to only increment the version suffix:

0.24+ubports3

Примечание

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

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

Now it is time to write your changelog entry! Start with the following template:

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 символов.

With that, my new changelog entry follows:

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»:

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

Give your pull request a descriptive title and description (include links to reference bugs or other material). Ensure that the «base» branch is the one you want your changes to be applied to (likely xenial), then click «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. Run sudo ubports-qa install REPOSITORY PR, replacing REPOSITORY with the name of the repository you have submitted a PR to and PR with the number of your pull request without the #. For example run sudo ubports-qa morph-browser 123 to install the PR number 123 to morph-browser repo.

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

If ubports-qa fails to install your packages, run it again with the -v flag (for example, ubports-qa -v install ...). If it still fails, submit the entire log (starting from the $ before the ubports-qa command) to Ubuntu Pastebin and contact us for help.

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

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

Every time you make a change and push it to GitHub, it will trigger a new build. You can run sudo ubports-qa update to get the freshest changes every time this happens.

Вот и всё!

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

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