Ubuntu logo

Packaging Guide

3. Corrigindo um erro no Ubuntu

3.1. Introdução

Se você seguiu as instruções do prepare-se para o Desenvolvimento do Ubuntu, você deve estar pronto para começar.

./_images/fixing-a-bug.png

Como você pode observar na imagem acima, não há surpresas no processo de correção de erros no Ubuntu: você encontra um problema, obtém o código, trabalha para corrigi-lo, testa, envia as alterações para o Launchpad e pede para que sejam revisadas e incorporadas. Neste guia nós passaremos por todas as etapas necessárias, uma por uma.

3.2. Encontrando o problema

Há várias maneiras diferentes de encontrar coisas nas quais trabalhar. Pode ser um relatório de erro que você mesmo encontrou (o que lhe dá uma boa oportunidade para testar a correção), ou um problema que você encontrou em outro lugar, talvez num relatório de erro.

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. Descobrindo o que corrigir

Se você não sabe qual o pacote fonte que contém o código que tem o problema, mas você sabe o caminho para o programa afetado no seu sistema, você pode descobrir o pacote fonte no qual você precisa trabalhar.

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

Isso deverá imprimir:

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 é parte da instalação padrão do Ubuntu.

3.4. Confirmando o problema

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

Digamos que o pacote “bumprace” não tenha uma página na Internet na sua descrição de pacote. Como primeiro passo, você iria verificar se o problema já esta solucionado. Isto é fácil de verificar, dê uma olhado na Central de Programas ou execute:

apt-cache show bumprace

A saída deve ser similar a isto:

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

Um contra-exemplo seria o “gedit”, que tem uma página na Internet definida:

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

Algumas vezes você ira descobrir que um problema em particular que você está analisando já está corrigido. Para evitar desperdiçar esforço e duplicar trabalho, faz sentido fazer um trabalho de detetive antes.

3.5. Pesquisar situação da falha

Primeiro temos que verificar um relatório de erro para o problema já existe no Ubuntu. Talvez alguém já esteja trabalhando em uma correção, ou que possamos contribuir para solução de alguma maneira. Para o Ubuntu, nós demos uma rápida olhada em https://bugs.launchpad.net/ubuntu/+source/bumprace e não há um relatório de erro ara o problema lá.

Nota

Para o Ubuntu a URL https://bugs.launchpad.net/ubuntu/+source/<pacote> deve sempre levar até a página de falhas do pacote fonte em questão.

Para o Debian, que é a maior fonte para os pacotes do Ubuntu, nós demos uma olhada em http://bugs.debian.org/src:bumprace e não achamos um relatório para o nosso problema também.

Nota

Para o Debian a URL http://bugs.debian.org/src:<pacote> deve sempre levar até a página de falhas do pacote fonte em questão.

The problem we are working on is special as it only concerns the packaging-related bits of bumprace. If it was a problem in the source code it would be helpful to also check the Upstream bug tracker. This is unfortunately often different for every package you have a look at, but if you search the web for it, you should in most cases find it pretty easily.

3.6. Oferecendo ajuda

Se você encontrou um relatório de erro aberto, se ele não estiver atribuído a alguém e você puder corrigi-lo, você deverá comentar no relatório a sua solução. Certifique-se de incluir toda a informação que puder: em que circunstâncias o erro acontece? Como você corrigiu o problema? Você testou a sua solução?

Se nenhum relatório de erro foi arquivado, você pode arquivá-lo. O que você deve ter em mente é: o problema é tão pequeno que pedir para alguém para repará-lo seria suficiente? Você conseguiu corrigir apenas parcialmente o problema e você quer ao menos compartilhar a sua parte na correção?

Isso é ótimo se você pode oferecer ajuda e certamente será apreciado.

3.7. Obtendo o código

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. trabalhar em uma correção

Há livros inteiros escritos sobre encontrar erros, corrigi-los, testá-los, etc. Se você for um programador novato, tente corrigir erros fáceis primeiro, como erros de digitação óbvios. Tente alterar o mínimo possível, e documente sua alteração e suposições com clareza.

Antes de trabalhar na correção você mesmo, tenha certeza de investigar se ninguém já corrigiu ou está trabalhando na correção para a falha. Boas fontes para verificar são:

  • Rastreamento de erros upstream (e Debian) de erros abertos e fechados,

  • Histórico de revisão do upstream (ou lançamento recente) poderia ter corrigido o problema,

  • bugs ou envio de pacotes do Debian ou outras distribuições.

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

Isso copiará o empacotamento para um diretório temporário. Agora você pode editar arquivos com um editor de textos ou aplicar patches do upstream, por exemplo:

$ patch -p1 < ../bugfix.patch

Após editar o tipo de arquivo exit ou pressione control-d para sair do shell temporário. O novo patch será adicionado em 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. Documentando a correção

É muito importante documentar a sua alteração suficientemente de maneira que os desenvolvedores que olharem o código no futuro não terão que adivinhar qual foi o seu raciocínio e quais foram a suposições. Todo pacote fonte do Debian e do Ubuntu inclui o “debian/changelog”, onde alterações em cada pacote enviado são rastreadas.

A maneira mais fácil de atualizar isto é executar:

$ dch -i

Isto irá adicionar um modelo entrada de registro de alteração para você e iniciar um editor onde você possa preencher os espaços em branco. Um exemplo disso poderia ser:

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 should fill out the first and last line of such a changelog entry for you already. Line 1 consists of the source package name, the version number, which Ubuntu release it is uploaded to, the urgency (which almost always is ‘low’). The last line always contains the name, email address and timestamp (in RFC 5322 format) of the change.

Com isso fora do caminho, vamos nos concentrar na entrada do registro de alteração propriamente dita: é muito importante documentar:

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

In our (very sparse) example the last point is covered by (LP: #123456) which refers to Launchpad bug 123456. Bug reports or mailing list threads or specifications are usually good information to provide as a rationale for a change. As a bonus, if you use the LP: #<number> notation for Launchpad bugs, the bug will be automatically closed when the package is uploaded to 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. Testando a correção

Para construir um pacote de teste com suas alterações, e execute estes comandos:

$ 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.

Nota

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.

Nota

In a lot of cases you will have to actually install the package to make sure it works as expected. Our case is a lot easier. If the build succeeded, you will find the binary packages in ~/pbuilder/<release>_result. Install them via sudo dpkg -i <package>.deb or by double-clicking on them in your file manager.

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

Isto lhe levará por uma série de passos para assegurar que o erro vá parar no lugar correto. Assegure-se de revisar o diff novamente para ter certeza de que não inclui alterações aleatórias que você tenha feito antes.

Comunicação é importante, então quando você adicionar alguma descrição para solicitar a inclusão, seja amigável, explique ela bem.

Se tudo deu certo você deverá receber um e-mail do sistema de rastreamento de erros do Debian com mais informações. Isto pode levar alguns minutos.

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. Considerações adicionais

Se você encontrar um pacote e achar que há algumas coisas pequenas que você pode corrigir ao mesmo tempo, faça isso. Isto irá acelerar a revisão e a inclusão.

Se há várias coisas grandes que você queira corrigir, é prudente que você envie patches individuais ou propostas de mesclagem. Se houver erros individuais já arquivados para esses problemas, isto facilita ainda mais.