Ubuntu logo

Packaging Guide

3. Виправлення помилок в Ubuntu

3.1. Вступ

Якщо Ви дотримувалися інструкцій з підготовки до розробки Ubuntu, усе повинно бути вже готово до роботи.

./_images/fixing-a-bug.png

Як Ви можете бачити на картинці вище, у процесі виправлення помилок в Ubuntu немає ніяких несподіванок: Ви знаходите проблему, отримуєте код, виправляєте його, тестуєте, відправляєте на Launchpad й прохаєте, щоб його перевірили та об’єднали з основним кодом. У цьому посібнику ми пройдемо через усі необхідні кроки, один за іншим.

3.2. Пошук проблеми

Існують різні способи знайти, над чим можна попрацювати. Це може бути помилка, яку Ви виявили самі (що дає Вам відмінну можливість перевірити своє виправлення) або проблема, яку Ви помітили десь ще, наприклад у звіті про ваду.

Take a look at the bitesize bugs in Launchpad, and that might give you an idea of something to work on. It might also interest you to look at the bugs triaged by the Ubuntu One Hundred Papercuts team.

3.3. З’ясування того, що потрібно виправити

Якщо Ви не знаєте, у якому пакунку джерельного коду міститься помилка, але знаєте шлях до цього застосунку у Вашій системі, то Ви зможете знайти пакунок джерельного коду, над яким потрібно попрацювати.

Let’s say you’ve found a bug in Bumprace, a racing game. The Bumprace application can be started by running /usr/bin/bumprace on the command line. To find the binary package containing this application, use this command:

$ apt-file find /usr/bin/bumprace

Команда виведе таку інформацію:

bumprace: /usr/bin/bumprace

Note that the part preceding the colon is the binary package name. It’s often the case that the source package and binary package will have different names. This is most common when a single source package is used to build multiple different binary packages. To find the source package for a particular binary package, type:

$ apt-cache showsrc bumprace | grep ^Package:
Package: bumprace
$ apt-cache showsrc tomboy | grep ^Package:
Package: tomboy

Команда apt-cache встановлена в Ubuntu типово.

3.4. Підтвердження проблеми

Once you have figured out which package the problem is in, it’s time to confirm that the problem exists.

Припустимо, у описі пакунку bumprace відсутня інформація про його домашню сторінку. У якості першого кроку, слід перевірити, чи не виправлена вже ця помилка. Зробити це просто: подивіться у Центрі додатків або запустіть:

apt-cache show bumprace

Вивід команди повинен бути приблизно таким:

Package: bumprace
Priority: optional
Section: universe/games
Installed-Size: 136
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XNBC-Original-Maintainer: Christian T. Steigies <cts@debian.org>
Architecture: amd64
Version: 1.5.4-1
Depends: bumprace-data, libc6 (>= 2.4), libsdl-image1.2 (>= 1.2.10),
         libsdl-mixer1.2, libsdl1.2debian (>= 1.2.10-1)
Filename: pool/universe/b/bumprace/bumprace_1.5.4-1_amd64.deb
Size: 38122
MD5sum: 48c943863b4207930d4a2228cedc4a5b
SHA1: 73bad0892be471bbc471c7a99d0b72f0d0a4babc
SHA256: 64ef9a45b75651f57dc76aff5b05dd7069db0c942b479c8ab09494e762ae69fc
Description-en: 1 or 2 players race through a multi-level maze
 In BumpRacer, 1 player or 2 players (team or competitive) choose among 4
 vehicles and race through a multi-level maze. The players must acquire
 bonuses and avoid traps and enemy fire in a race against the clock.
 For more info, see the homepage at http://www.linux-games.com/bumprace/
Description-md5: 3225199d614fba85ba2bc66d5578ff15
Bugs: https://bugs.launchpad.net/ubuntu/+filebug
Origin: Ubuntu

У якості контрприкладу можна привести gedit, де домашня сторінка вказана:

$ apt-cache show gedit | grep ^Homepage
Homepage: http://www.gnome.org/projects/gedit/

У деяких випадках Ви можете зіштовхнутися з тим, що проблема, вирішення якої Ви шукаєте, вже кимось усунена. Щоб уникнути даремного витрачення часу й праці, має сенс проробити деяку детективну роботу.

3.5. Вивчення ситуації з помилкою

Спочатку потрібно перевірити, чи не існує вже повідомлення про цю помилку в Ubuntu. Можливо, хтось вже працює над її виправленням, або ми можемо якось внести свій внесок у вирішення цієї проблеми. Для Ubuntu ми поглянемо на https://bugs.launchpad.net/ubuntu/+source/bumprace й побачимо, що відкритого звіту про нашу ваду там немає.

Примітка

Для Ubuntu URL https://bugs.launchpad.net/ubuntu/+source/<пакунок> завжди приводить на сторінку помилок у вказаномум пакунку джерельного коду.

У Debian, який є основним джерелом пакунків Ubuntu ми поглянемо на http://bugs.debian.org/src:bumprace й також не знайдемо там повідомлення про нашу ваду.

Примітка

Для Debian URL http://bugs.debian.org/src:<пакет> завжди приводить на сторінку помилок у вказаному пакунку джерельного коду.

Помилка, над якою ми працюємо, незвичайна у тому сенсі, що вона стосується лише пакункування bumprace. Якби це була вада у джерельному коді, корисно було б також перевірити систему відстеження помилок апстріму. Нажаль, ця процедура часто різниться для кожного окремого пакунку, але завжди можна скористатися пошуком в інтернеті, й у більшості випадків Ви з’ясуєте, що вона виявиться не такою вже й складною.

3.6. Пропозиція допомоги

Якщо Ви виявили відкриту ваду, яка ще нікому не призначена, й Ви готові взятися за її усунення, слід написати коментар з Вашим вирішенням. Включіть у нього щонайбільше інформації: При яких обставинах з’являється помилка? Як Ви її виправили? Чи тестували Ви свій спосіб усунення помилки?

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

Буде чудово, якщо Ви можете запропонувати свою допомогу, й вона, без сумніву, буде з готовністю прийнята.

3.7. Отримання коду

Once you know the source package to work on, you will want to get a copy of the code on your system, so that you can debug it. The ubuntu-dev-tools package has a tool called pull-lp-source that a developer can use to grab the source code for any package. For example, to grab the source code for the tomboy package in xenial, you can type this:

$ pull-lp-source bumprace xenial

If you do not specify a release such as xenial, it will automatically get the package from the development version.

Once you’ve got a local clone of the source package, you can investigate the bug, create a fix, generate a debdiff, and attach your debdiff to a bug report for other developers to review. We’ll describe specifics in the next sections.

3.8. Виправлення помилки

Є цілі книги про знаходження помилок, їх виправлення, тестування й так далі. Якщо Ви початківець у проґрамуванні, спробуйте виправляти нескладні помилки, такі як очевидні друкарські помилки. Намагайтеся робити Ваші зміни мінімальними й чітко документувати Ваші зміни та припущення.

Перед тим, як працювати над помилкою, переконайтеся, що вона не виправлена вже кимось іншим, й ніхто не займається на дану мить її виправленням. Не завадить перевірити наступні джерела:

  • Система відстеження помилок апстріму (й Debian) — відкриті та закриті помилки,

  • Історія версій в апстрімі (або у новій версії) може містити відомості про виправлення помилки,

  • звіти про вади й нові версії пакунків в Debian та інших дистрибутивах.

You may want to create a patch which includes the fix. The command edit-patch is a simple way to add a patch to a package. Run:

$ edit-patch 99-new-patch

Ця команда скопіює файли, необхідні для збірки пакунку, у тимчасову директорію. Ви можете змінювати ці файли у текстовому редакторі або застосовувати латки з upstream, наприклад:

$ patch -p1 < ../bugfix.patch

Після редагування файлу наберіть exit або натисніть control-d, щоб вийти з тимчасової командної оболонки. Нова латка буде додана в debian/patches.

You must then add a header to your patch containing meta information so that other developers can know the purpose of the patch and where it came from. To get the template header that you can edit to reflect what the patch does, type this:

$ quilt header --dep3 -e

This will open the template in a text editor. Follow the template and make sure to be thorough so you get all the details necessary to describe the patch.

In this specific case, if you just want to edit debian/control, you do not need a patch. Put Homepage: http://www.linux-games.com/bumprace/ at the end of the first section and the bug should be fixed.

3.8.1. Документування виправлення

Дуже важливо документувати свої зміни у достатній мірі, щоб розробникам потім не довелося здогадуватися, якими були причини й передумови зроблених Вами змін. Кожен пакунок джерельного коду Debian та Ubuntu включає у себе файл debian/changelog, у якому відстежуються вносювані у пакунок зміни.

Найпростіший спосіб оновити його — це виконати:

$ dch -i

Ця команда додасть у файл шаблон запису й запустить редактор, у якому Ви зможете додати інформацію якої бракує. Ось приклад цього запису:

specialpackage (1.2-3ubuntu4) trusty; urgency=low

  * debian/control: updated description to include frobnicator (LP: #123456)

 -- Emma Adams <emma.adams@isp.com>  Sat, 17 Jul 2010 02:53:39 +0200

Команда dch повинна заповнити перший і останній рядок цього запису у файлі changelog. Перший рядок містить ім’я пакунку джерельного коду, номер його версії, у який реліз Ubuntu він завантажений, терміновість (майже завжди низька — ‘low’). Останній рядок завжди містить ім’я, адресу електронної пошти та мітку часу змінювання (у форматі RFC 5322).

Тепер давайте сфокусуємося на тому що має міститися у самому запису файлу changelog. Дуже важливо задокументувати:

  1. Where the change was done.
  2. What was changed.
  3. Where the discussion of the change happened.

У нашому (досить поодинокому) прикладі останньому пункту відповідає (LP: #123456), тобто посилання на помилку на Launchpad з номером 123456. Звіти про вади, теми переліків розсилки або специфікації зазвичай є добрими джерелами інформації для обґрунтування змін. У якості додаткового заохочення, якщо Ви використовуєте нотацію LP: #<номер> для помилок на Launchpad, то помилка автоматично отримає статус закритої при відправці пакунку в Ubuntu.

In order to get it sponsored in the next section, you need to file a bug report in Launchpad (if there isn’t one already, if there is, use that) and explain why your fix should be included in Ubuntu. For example, for tomboy, you would file a bug here (edit the URL to reflect the package you have a fix for). Once a bug is filed explaining your changes, put that bug number in the changelog.

3.9. Тестування виправлення

Щоб зібрати тестовий пакунок з Вашими змінами, виконайте такі команди:

$ debuild -S -d -us -uc
$ pbuilder-dist <release> build ../<package>_<version>.dsc

This will create a source package from the branch contents (-us -uc will just omit the step to sign the source package and -d will skip the step where it checks for build dependencies, pbuilder will take care of that) and pbuilder-dist will build the package from source for whatever release you choose.

Примітка

If debuild errors out with “Version number suggests Ubuntu changes, but Maintainer: does not have Ubuntu address” then run the update-maintainer command (from ubuntu-dev-tools) and it will automatically fix this for you. This happens because in Ubuntu, all Ubuntu Developers are responsible for all Ubuntu packages, while in Debian, packages have maintainers.

In this case with bumprace, run this to view the package information:

$ dpkg -I ~/pbuilder/*_result/bumprace_*.deb

As expected, there should now be a Homepage: field.

Примітка

У більшості випадків Вам доведеться дійсно встановити пакунок, щоб перевірити правильність його роботи. Наш випадок на багато простіший. Якщо збірка завершилася з успіхом, готові двійкові пакунки можна буде знайти в ~/pbuilder/<випуск>_result. Встановіть їх за допомогою sudo dpkg -i <пакунок>.deb або подвійного клацу на них у файловому менеджері.

3.10. Submitting the fix and getting it included

With the changelog entry written and saved, run debuild one more time:

$ debuild -S -d

and this time it will be signed and you are now ready to get your diff to submit to get sponsored.

In a lot of cases, Debian would probably like to have the patch as well (doing this is best practice to make sure a wider audience gets the fix). So, you should submit the patch to Debian, and you can do that by simply running this:

$ submittodebian

Ця команда проведе Вас через декілька кроків, необхідних для оформлення звіту про ваду й відправки його у правильне місце. Обов’язково продивіться Ваші зміни, щоб переконатися, що там немає нічого зайвого.

Комунікація має дуже велике значення, тому при додаванні опису надайте добре та дружнє пояснення.

Якщо усе пройшло добре, то Ви повинні отримати поштове повідомлення від системи відстежування помилок Debian з додатковою інформацією. Інколи це може зайняти декілька хвилин.

It might be beneficial to just get it included in Debian and have it flow down to Ubuntu, in which case you would not follow the below process. But, sometimes in the case of security updates and updates for stable releases, the fix is already in Debian (or ignored for some reason) and you would follow the below process. If you are doing such updates, please read our Security and stable release updates article. Other cases where it is acceptable to wait to submit patches to Debian are Ubuntu-only packages not building correctly, or Ubuntu-specific problems in general.

But if you’re going to submit your fix to Ubuntu, now it’s time to generate a “debdiff”, which shows the difference between two Debian packages. The name of the command used to generate one is also debdiff. It is part of the devscripts package. See man debdiff for all the details. To compare two source packages, pass the two dsc files as arguments:

$ debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc

In this case, debdiff the dsc you downloaded with pull-lp-source and the new dsc file you generated. This will generate a patch that your sponsor can then apply locally (by using patch -p1 < /path/to/debdiff). In this case, pipe the output of the debdiff command to a file that you can then attach to the bug report:

$ debdiff <package_name>_1.0-1.dsc <package_name>_1.0-1ubuntu1.dsc > 1-1.0-1ubuntu1.debdiff

The format shown in 1-1.0-1ubuntu1.debdiff shows:

  1. 1- tells the sponsor that this is the first revision of your patch. Nobody is perfect, and sometimes follow-up patches need to be provided. This makes sure that if your patch needs work, that you can keep a consistent naming scheme.
  2. 1.0-1ubuntu1 shows the new version being used. This makes it easy to see what the new version is.
  3. .debdiff is an extension that makes it clear that it is a debdiff.

While this format is optional, it works well and you can use this.

Next, go to the bug report, make sure you are logged into Launchpad, and click “Add attachment or patch” under where you would add a new comment. Attach the debdiff, and leave a comment telling your sponsor how this patch can be applied and the testing you have done. An example comment can be:

This is a debdiff for Artful applicable to 1.0-1. I built this in pbuilder
and it builds successfully, and I installed it, the patch works as intended.

Make sure you mark it as a patch (the Ubuntu Sponsors team will automatically be subscribed) and that you are subscribed to the bug report. You will then receive a review anywhere between several housr from submitting the patch to several weeks. If it takes longer than that, please join #ubuntu-motu on freenode and mention it there. Stick around until you get an answer from someone, and they can guide you as to what to do next.

Once you have received a review, your patch was either uploaded, your patch needs work, or is rejected for some other reason (possibly the fix is not fit for Ubuntu or should go to Debian instead). If your patch needs work, follow the same steps and submit a follow-up patch on the bug report, otherwise submit to Debian as shown above.

Remember: good places to ask your questions are ubuntu-motu@lists.ubuntu.com and #ubuntu-motu on freenode. You will easily find a lot of new friends and people with the same passion that you have: making the world a better place by making better Open Source software.

3.11. Додаткові зауваження

Якщо Ви можете внести у пакунок декілька тривіальних виправлень одразу, зробіть це. Це дозволить розробникам швидше розглянути й застосувати ці зміни.

Якщо Ви бажаєте внести декілька великих змін, краще посилати латки або запити на злиття окремо для кожної зміни. Це простіше, якщо вже створені індивідуяльні повідомлення про вади.