« back to all changes in this revision
Viewing changes to fixing-a-bug.rst
- browse files at revision 22
- compare with another revision
- download diff
- download tarball
- view history from revision 22
- Committer: Barry Warsaw
- Date: 2011-03-09 12:41:16 UTC
- mfrom: (20.2.10 udd)
- Revision ID: barry@python.org-20110309124116-qqjo186rt2vxspzu
Merge Ubuntu Distributed Development documentation from the wiki into the
packaging guide. This needs a bit more reorganization, but it's a good first
step to merging the content from the UDD wiki pages.
packaging guide. This needs a bit more reorganization, but it's a good first
step to merging the content from the UDD wiki pages.
added
removed
fixing-a-bug.rst
1
======================
1
2
Fixing a bug in Ubuntu
2
3
======================
3
4
4
5
Introduction
5
------------
6
============
6
7
7
8
If you followed the instructions to :doc:`get set up with Ubuntu
8
9
Development</getting-set-up>`, you should be all set and ready to go.
16
17
17
18
18
19
Finding the problem
19
-------------------
20
===================
20
21
21
22
There is a lot of different ways to find things to work on. It might be a bug
22
23
report you are encountering yourself (which gives you a good opportunity to
28
29
it out and find your first bug to work on.
29
30
30
31
31
Get the code
32
------------
33
34
If you know which source package contains the code that shows the problem, it
35
is trivial. Just type in::
36
37
bzr branch lp:ubuntu/<packagename>
38
39
where ``<packagename>`` is the name of the source package. This will check out
40
the code of the latest Ubuntu development release. If you need the code of a
41
stable release, let's say ``hardy``, you would type in::
42
43
bzr branch lp:ubuntu/hardy/<packagename>
32
.. _what-to-fix:
33
34
Figuring out what to fix
35
========================
36
37
If you don't know the source package containing the code that has the problem,
38
but you do know the path to the affected program on your system, you can
39
discover the source package that you'll need to work on.
40
41
Let's say you've found a bug in Tomboy, a note taking desktop application.
42
The Tomboy application can be started by running ``/usr/bin/tomboy`` on the
43
command line. To find the binary package containing this application, use
44
this command::
45
46
$ apt-file find /usr/bin/tomboy
47
48
This would print out::
49
50
tomboy: /usr/bin/tomboy
51
52
Note that the part preceding the colon is the binary package name. It's often
53
the case that the source package and binary package will have different names.
54
This is most common when a single source package is used to build multiple
55
different binary packages. To find the source package for a particular binary
56
package, type::
57
58
$ apt-cache show tomboy | grep ^Source:
59
60
In this case, nothing is printed, meaning that ``tomboy`` is also the name of
61
the binary package. An example where the source and binary package names
62
differ is ``python-vigra``. While that is the binary package name, the source
63
package is actually ``libvigraimpex`` and can be found with this command (and
64
its output)::
65
66
$ apt-cache show python-vigra | grep ^Source:
67
Source: libvigraimpex
44
68
45
69
.. XXX: Link to SRU article.
46
70
47
71
48
Work on fix
49
-----------
72
Getting the code
73
================
74
75
Once you know the source package to work on, you will want to get a copy of
76
the code on your system, so that you can debug it. This is done by
77
:ref:`*branching* the source package <branching>` branch corresponding to the
78
source package. Launchpad maintains source package branches for all the
79
packages in Ubuntu.
80
81
Once you've got a local branch of the source package, you can investigate the
82
bug, create a fix, and upload your proposed fix to Launchpad, in the form of a
83
Bazaar branch. When you are happy with your fix, you can :ref:`submit a
84
*merge proposal* <merge-proposal>`, which asks other Ubuntu developers to
85
review and approve your change. If they agree with your changes, an Ubuntu
86
developer will upload the new version of the package to Ubuntu so that
87
everyone gets the benefit or your excellent fix - and you get a little bit of
88
credit. You're now on your way to becoming an Ubuntu developer!
89
90
We'll describe specifics on how to branch the code, push your fix, and request
91
a review in the following sections.
92
93
94
Work on a fix
95
=============
50
96
51
97
There are entire books written about finding bugs, fixing them, testing them,
52
98
etc. If you are completely new to programming, try to fix easy bugs such as
62
108
63
109
.. XXX: Link to 'update to a new version' article.
64
110
65
66
If you find a patch to fix the problem, running this command in the source
67
directory should apply the patch::
68
69
patch -p1 < ../bugfix.patch
111
If you find a patch to fix the problem, say, attached to a bug report, running
112
this command in the source directory should apply the patch::
113
114
$ patch -p1 < ../bugfix.patch
70
115
71
116
Refer to the ``patch(1)`` manpage for options and arguments such as
72
117
``--dry-run``, ``-p<num>``, etc.
73
74
75
Testing the fix
76
---------------
77
78
To build a test package with your changes, run these commands::
79
80
bzr bd -- -S -us -uc
81
pbuilder-dist <release> build ../<package>_<version>.dsc
82
83
This will create a source package from the branch contents (``-us -uc`` will
84
just omit the step to sign the source package) and pbuilder-dist will build
85
the package from source for whatever ``release`` you choose.
86
87
Once the build succeeded, install the package from
88
``~/pbuilder/<release>_result/`` (using ``sudo dpkg -i
89
<package>_<version>.deb``). Then test to see if the bug is fixed.
90
91
92
93
Documenting the fix
94
-------------------
95
96
It is very important to document your change sufficiently so developers who
97
look at the code in the future won't have to guess what your reasoning was and
98
what your assumptions were. Every Debian and Ubuntu package source includes
99
``debian/changelog``, where changes of each uploaded package are tracked.
100
101
The easiest way to do this is to run::
102
103
dch -i
104
105
This will add a boilerplate changelog entry for you and launch an editor
106
where you can fill out the blanks. An example of this could be::
107
108
specialpackage (1.2-3ubuntu4) natty; urgency=low
109
110
* debian/control: updated description to include frobnicator (LP: #123456)
111
112
-- Emma Adams <emma.adams@isp.com> Sat, 17 Jul 2010 02:53:39 +0200
113
114
``dch`` should fill out the first and last line of such a changelog entry for
115
you already. Line 1 consists of the source package name, the version number,
116
which Ubuntu release it is uploaded to, the urgency (which almost always is
117
'low'). The last line always contains the name, email address and timestamp
118
(in RFC 2822 format) of the change.
119
120
With that out of the way, let's focus on the actual changelog entry itself:
121
it is very important to document:
122
123
#. where the change was done
124
#. what was changed
125
#. where the discussion of the change happened
126
127
In our (very sparse) example the last point is covered by "(LP: #123456)"
128
which refers to Launchpad bug 123456. Bug reports or mailing list threads
129
or specifications are usually good information to provide as a rationale for a
130
change. As a bonus, if you use the ``LP: #<number>`` notation for Launchpad
131
bugs, the bug will be automatically closed when the package is uploaded to
132
Ubuntu.
133
134
135
Committing the fix
136
------------------
137
138
With the changelog entry written and saved, you can just run::
139
140
debcommit
141
142
and the change will be committed (locally) with your changelog entry as a
143
commit message.
144
145
To push it to Launchpad, as the remote branch name, you need to stick to the
146
following nomenclature::
147
148
lp:~<yourlpid>/ubuntu/<release>/<package>/<branchname>
149
150
This could for example be::
151
152
lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
153
154
So if you just run::
155
156
bzr push lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
157
bzr lp-open
158
159
you should be all set. The push command should push it to Launchpad and the
160
second command will open the Launchpad page of the remote branch in your
161
browser. There find the "(+) Propose for merging" link, click it to get the
162
change reviewed by somebody and included in Ubuntu.
163
164
165
Conclusion
166
----------
167
168
.. XXX: link to 'forwarding patches' article
169
.. XXX: link to 'debdiff' article (in case of slow internet, package not
170
imported, etc.)
171
Loggerhead is a web-based interface for Breezy
Version: 2.0.1