Dev Week -- Debdiffs And How To Get Them Submitted -- Daniel Holbach -- Tue, Feb 19

see also Thursday session.

(03:01:44 PM) dholbach: OK, let's get started on debdiffs
(03:02:24 PM) dholbach: Debdiffs are the preferred form of submitting patches, developers who sponsor your uploads will be happy if you stick to that form :)
(03:02:51 PM) dholbach: if you have questions or I'm too quick, please don't hesitate to ask your "QUESTION: ..." on #ubuntu-classroom-chat :-)
(03:03:13 PM) dholbach: ok... we need just a bit of preparation for this session
(03:03:37 PM) dholbach: can you all please add something similar to these two lines to your ~/.bashrc (or .zshrc depending on which shell you use):
(03:03:43 PM) dholbach: export DEBFULLNAME='Daniel Holbach'
(03:03:43 PM) dholbach: export DEBEMAIL=''
(03:04:06 PM) dholbach: I was informed that just setting DEBEMAIL to "your name <>" will work too, but I never tried :)
(03:04:35 PM) dholbach: once you've done that, please either restart your terminal or run   source ~/.bashrc
(03:04:43 PM) dholbach: everybody all set?
(03:04:52 PM) dholbach: give me your +1 if you are
(03:04:52 PM) ***InsClusoe nods his head.
(03:05:02 PM) InsClusoe: +1
(03:05:16 PM) dholbach: that's one - who's here for the session today? :)
(03:05:31 PM) jcastro: me!
(03:05:33 PM) dholbach: oh my... everybody's sleeping already :)
(03:05:35 PM) ninkendo: me!
(03:05:42 PM) WhiteEagle: me ;)
(03:05:42 PM) joejaxx: i am here still :D
(03:05:43 PM) dustinlange: +1
(03:05:43 PM) eddyMul: me
(03:05:58 PM) dholbach: excellent
(03:06:14 PM) dholbach: DEBFULLNAME and DEBEMAIL are used by a set of packaging tools and will make your life much much easier
(03:06:34 PM) dholbach: next we'll have to install a few tools:    sudo apt-get install devscripts build-essential wget fakeroot cdbs patchutils debhelper
(03:06:54 PM) dholbach: devscripts contain a bunch of tools for debian/ubuntu packages
(03:07:09 PM) dholbach: build-essential is a metapackage which pulls in gcc, make and the like
(03:07:17 PM) dholbach: wget is used for downloading stuff from the net
(03:07:35 PM) dholbach: fakeroot is used to emulate "root privileges" during the build
(03:07:55 PM) dholbach: cdbs is used by the package we're about to patch (a set of makefile snippets to make writing debian/rules files easier)
(03:08:05 PM) dholbach: patchutils and debhelper are needed too
(03:08:55 PM) dholbach: OK... we're all in bug fixing mode
(03:09:16 PM) TuxCrafter: +1
(03:09:18 PM) dholbach: let's suppose we got a bug report saying that the xicc package has 'colour' instead of 'color' in its description
(03:09:33 PM) dholbach: of course the bug report would be ridiculous and we'd close it
(03:09:46 PM) dholbach: but just assume it for the sake of getting out debdiff together :)
(03:09:55 PM) dholbach: first we'd verify if this really is the case
(03:10:08 PM) dholbach:    apt-cache show xicc
(03:10:19 PM) dholbach: shows it's really "colour", so we'll "fix" that
(03:10:45 PM) dholbach: oh... also make sure you have a    deb-src    line in your /etc/apt/sources.list
(03:11:00 PM) dholbach: for gutsy that'd be:
(03:11:01 PM) dholbach: deb-src gutsy main restricted universe multiverse
(03:11:12 PM) dholbach: replace gutsy with whatever release you're using
(03:11:15 PM) dholbach: then run:
(03:11:18 PM) dholbach:   sudo apt-get update
(03:11:47 PM) dholbach: next we'll get the source package for xicc
(03:11:51 PM) dholbach:    apt-get source xicc
(03:12:15 PM) dholbach: it downloaded the following files for us: xicc_0.2-2.diff.gz  xicc_0.2-2.dsc  xicc_0.2.orig.tar.gz
(03:12:46 PM) dholbach: the .orig.tar.gz file is the tarball the xicc upstream authors released on their website as-is
(03:13:09 PM) dholbach: the .diff.gz is the compressed changes that are necessary to make xicc build in a debian build environment
(03:13:25 PM) dholbach: the .dsc file is a description file containing md5sums and the like
(03:13:52 PM) dholbach: "apt-get source" used "dpkg-source -x" internally to extract the tarball and apply the diff.gz changes to it
(03:14:03 PM) dholbach:   cd xicc-0.2
(03:14:09 PM) dholbach:   cat debian/control
(03:14:54 PM) dholbach: the debian/control file contains information about the source package (which packages are necessary to make it build, who is the maintainer, etc.) and the binary package (the one my mom would install)
(03:15:05 PM) dholbach: you can see 'colour' in the binary package description
(03:15:18 PM) dholbach: let's change colour to color then
(03:15:22 PM) dholbach:   sed -i 's/colour/color/g' debian/control
(03:15:45 PM) InsClusoe: +1
(03:16:02 PM) dholbach: did everybody get it working?
(03:16:07 PM) jcastro: yep
(03:16:11 PM) ninkendo: yep
(03:16:11 PM) Yasumoto: +1
(03:16:18 PM) dholbach: brilliant
(03:16:20 PM) joumetal: +1
(03:16:27 PM) barcc: +1
(03:16:43 PM) dholbach: next we'll write a changelog entry to document what we've done - this is essential to what you do when you change a package
(03:17:01 PM) TuxCrafter: +1
(03:17:16 PM) dholbach: in the Ubuntu world we maintain packages as a team, so if you change a package somebody else might come up half a year later and wonder WHY you did those changes :)
(03:17:26 PM) dholbach: so better get it right and document it in the first plafce
(03:17:27 PM) dholbach: place
(03:17:31 PM) dholbach: please run
(03:17:32 PM) dholbach:   dch -i
(03:17:57 PM) dholbach: this is a nifty tool from the devscripts package that makes use of DEBEMAIL and DEBFULLNAME we just set
(03:18:31 PM) dholbach: the first line contains the following items:
(03:18:59 PM) dholbach: <source package name> (<version string>)  <release of Ubuntu you upload to>; <urgency>
(03:19:11 PM) dholbach: we can ignore the urgency for now - it's not relevant to Ubuntu
(03:19:15 PM) dholbach: source package name is xicc
(03:19:31 PM) dholbach: what about the version string? what does it consist of?
(03:19:50 PM) dholbach: as we've seen in  xicc_0.2.orig.tar.gz  the upstream version number is 0.2
(03:20:04 PM) dholbach: the next part of it is the debian/ubuntu revision
(03:20:41 PM) InsClusoe: <debian-version><ubuntu><revision-number>
(03:20:43 PM) dholbach: -2ubuntu1 means: revision 2 in debian, and an ubuntu change on top of that
(03:20:54 PM) dholbach: InsClusoe: right, that's true for packages where we do changes
(03:21:06 PM) dholbach: most of the debian packages go into ubuntu unchanged
(03:21:15 PM) dholbach: so we stick to      <upstream>-<debian revision>
(03:21:45 PM) james_w: dogi> QUESTION: after 'apt-get source xicc' there wos a of 'gpg:' - messages is that normal?
(03:21:49 PM) dholbach: if we should decide to ship xicc 0.3 (if it was available), we'd name it 0.3-0ubuntu1 as it is not in Debian yet or at least our version is not based on the debian one
(03:22:24 PM) dholbach: dogi: good question: you can ignore that - it's just a warning telling you that you don't have the key of ross burton who happened to do the last upload of xicc
(03:22:31 PM) james_w: <Solarion> QUESTION: why the DEB* env vars instead of respecting existing data (e.g. GECOS field, username?)
(03:23:06 PM) dholbach: Solarion: I think the patch for devscripts to make it use GECOS fields has not been written yet
(03:23:34 PM) dholbach: indicates there's no bug report open for that yet
(03:23:47 PM) dholbach: it'd certainly be nice to have though
(03:23:49 PM) james_w: I think it falls back to the normal fields, but allows you to use these on top to change your identity for packaging.
(03:24:07 PM) dholbach: oh ok, good to know
(03:24:26 PM) dholbach: any more questions?
(03:24:27 PM) james_w: search for DEBEMAIL in man dch and all is explained
(03:24:35 PM) dholbach: great :)
(03:24:37 PM) james_w: <james_w> Question: what does the '-i' in the dch command do?
(03:25:08 PM) dholbach: james_w: it inserts a new changelog entry and increments the version number
(03:25:15 PM) james_w: <eddyMul> QUESTION: how to use `dch -i` from emacs' shell?
(03:25:32 PM) dholbach: there are other scenarios where you might not want to do that, let's assume you're working on a huge revision together with friends and co-maintainers
(03:25:46 PM) dholbach: in that case you use dch -e
(03:26:25 PM) dholbach: eddyMul: I haven't used emacs for years, so I guess I'm the wrong person to answer your question - I could just answer how you switch to a different one, sorry :)
(03:26:48 PM) dholbach: maybe  devscripts-el  has some love for emacs
(03:26:51 PM) eddyMul: dholbach: it's minute detail. I'll survive w/ nano. carry on
(03:26:51 PM) dholbach: I'm sorry - I don't know
(03:27:06 PM) dholbach: I set  EDITOR=vi  - sorry
(03:27:19 PM) dholbach: ok... back to our changelog
(03:27:55 PM) dholbach: now that we've covered the version string, next is the ubuntu release we upload to
(03:28:10 PM) dholbach: we generally can only upload to the current development release, which in our case is 'hardy'
(03:28:35 PM) dholbach: of course there's also "gutsy-updates" and "gutsy-security" etc, but that's something you can learn more about in tomorrow's session
(03:28:45 PM) dholbach: SRU/Security Updates (Luca Falavigna, William Grant)
(03:28:57 PM) dholbach: so we'll set it to hardy and leave the urgency as is
(03:29:29 PM) dholbach: as actual changelog entry, I set:
(03:29:30 PM) dholbach:   * debian/control: replace 'colour' with 'color'.
(03:29:41 PM) dholbach: note how I refer to the file I changed and what I did with it
(03:30:17 PM) dholbach: as we're working on an (imaginative, granted) bug we'd add something along the lines of  (LP: #123456)  to that line
(03:30:22 PM) dholbach: to indicate: we fixed bug 123456
(03:30:33 PM) dholbach: once the actual upload happens the bug will be closed automatically
(03:30:55 PM) dholbach: ok... change done and documented
(03:31:27 PM) dholbach: now we come to something our friends at Debian asked us to do when we change any Debian package
(03:31:41 PM) dholbach: (remember we changed it from 0.2-2 to 0.2-2ubuntu1)
(03:31:43 PM) dholbach:
(03:31:52 PM) dholbach: we'll need to edit  debian/control  again
(03:32:02 PM) james_w: <Solarion> QUESTION: regarding numbering scheme, what if there's no Debian version?
(03:32:03 PM) dholbach: and replace
(03:32:04 PM) dholbach:   Maintainer: Ross Burton <>
(03:32:10 PM) dholbach: with
(03:32:11 PM) dholbach: XSBC-Original-Maintainer: Ross Burton <>
(03:32:12 PM) dholbach: Maintainer: Ubuntu MOTU Developers <>
(03:32:41 PM) dholbach: Solarion: good question - in that case we'll name it    0.3-0ubuntu1   (0 because there was no debian revision of it yet)
(03:32:55 PM) james_w: <eddyMul> QUESTION: what if we touched a bunch of files in patching it? should I still put multiple files? what would it look like? (e.g. modified debian/rules to have a dh_install, then added debian/install for list of files)
(03:33:28 PM) dholbach: eddyMul: there's no strict policy, but I prefer to mention all the changes I've done
(03:33:41 PM) dholbach: so if you have one big change that consist of changes in various files you could do something like:
(03:34:08 PM) eddyMul: dholbach: so, for my example, can you show me how you would document it?
(03:34:10 PM) dholbach:   * debian/control, debian/rules, debian/patches/01_frobnication.patch:  make sure frobnication is executed after configuration.
(03:34:24 PM) eddyMul: dholbach: got it. thanx.
(03:34:50 PM) dholbach: or something along the lines of:
(03:34:51 PM) dholbach:   * debian/
(03:34:51 PM) dholbach:     - Updated library dependency versions based on
(03:34:51 PM) dholbach:   * debian/patches/01_lpi.patch:
(03:34:51 PM) dholbach:     - Updated
(03:34:51 PM) dholbach:   * debian/patches/90_autoconf.patch:
(03:34:53 PM) dholbach:     - Updated via automagic
(03:35:01 PM) dholbach: as I said: there's no strict policy
(03:35:34 PM) dholbach: if you're not afraid of getting a lot of emails, check out the hardy-changes list to see all the changes that are made during the hardy release and how they are documented :)
(03:35:42 PM) dholbach: back to the maintainer field change
(03:35:55 PM) dholbach: in  XSBC-Original-Maintainer:  preserve the original maintainer
(03:36:13 PM) dholbach: but setting the Maintainer field to an Ubuntu list ensures that none of our users mail the debian maintainer accidentally
(03:36:28 PM) dholbach: this was decided by all debian maintainers is understandable
(03:36:45 PM) dholbach: the tool    update-maintainer   (also in ubuntu-dev-tools) does that automatically for you :)
(03:36:56 PM) dholbach: let's document that change too
(03:36:59 PM) dholbach: dch -e
(03:37:21 PM) dholbach: something along the lines of:
(03:37:22 PM) dholbach:   * debian/control:
(03:37:22 PM) dholbach:     - replace 'colour' with 'color'.
(03:37:22 PM) dholbach:     - changed Maintainer field.
(03:37:23 PM) dholbach: will do
(03:37:37 PM) dholbach: now we're all set and happy with our changes :)
(03:37:53 PM) dholbach: let's build the new source package (including .diff.gz and .dsc) for the 0.2-2ubuntu1 release
(03:38:01 PM) dholbach: please run      debuild -S
(03:38:22 PM) dholbach: (for some of you it might complain about a missing GPG key - please ignore that - it's irrelevant right now)
(03:38:39 PM) dholbach: has more info on how to set it up properly
(03:38:50 PM) dholbach: all set?
(03:38:56 PM) jcastro: yep!
(03:39:04 PM) Yasumoto: +1
(03:39:08 PM) InsClusoe: +1
(03:39:13 PM) thekorn: yes
(03:39:28 PM) dholbach: great
(03:39:40 PM) dholbach: cd ..
(03:39:42 PM) dholbach: ls
(03:39:56 PM) eddyMul: +1
(03:40:06 PM) dholbach: now we have: xicc_0.2-2ubuntu1.diff.gz  xicc_0.2-2ubuntu1.dsc  xicc_0.2-2ubuntu1_source.changes
(03:40:26 PM) dholbach: tihs is the new source package for our changed xicc package
(03:40:42 PM) dholbach: if you now run:
(03:40:44 PM) dholbach:    debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc  > debdiff
(03:41:02 PM) dholbach: debdiff will diff the two source packages and write it to a file called debdiff
(03:41:32 PM) dholbach: can you paste your debdiff into and paste the link here?
(03:41:53 PM) ninkendo: QUESTION: will the debdiff command only find changes in the debian/ directory?  Or does it scan the entire source tree for changes?
(03:42:01 PM) jcastro:
(03:42:12 PM) dholbach: ninkendo: the entire tree
(03:42:18 PM) InsClusoe:
(03:42:29 PM) dholbach: good work jcastro
(03:42:38 PM) ninkendo:
(03:42:39 PM) eddyMul:
(03:42:49 PM) dholbach: InsClusoe: you used my name in DEBEMAIL and DEBFULLNAME :-)
(03:43:23 PM) InsClusoe: Thats the best way to survive any mistakes that I do in packaging... :-)
(03:43:26 PM) dholbach: eddyMul: xicc-0.2.orig/debian/ should probably not be in the debdiff - make sure you delete it and re-run debuild -S + debdiff
(03:43:30 PM) dholbach: InsClusoe: hahaha :)
(03:43:47 PM) dholbach: good work ninkendo
(03:44:00 PM) dholbach: well done everybody
(03:44:17 PM) Yasumoto:
(03:44:17 PM) dholbach: our first debdiff is in good shape we're ready to get it reviewed and uploaded
(03:44:34 PM) dholbach: looking good Yasumoto
(03:44:38 PM) Yasumoto: thanks dholbach :)
(03:44:38 PM) Pricey is now known as PriceChild
(03:45:05 PM) james_w: <eddyMul> QUESTION: is there a way to have debdiff ignore some files (e.g. emacs_backup_files~)
(03:45:06 PM) dholbach: now we come to one of the most essential processes in contributing to Ubuntu development: the sponsoring process
(03:45:43 PM) dholbach: eddyMul: you can run filterdiff on the debdiff afterwards or use    debdiff --exlude <pattern>
(03:46:13 PM) dholbach: but generally it's better to clean up the directory and make the change as minimal as necessary and possible
(03:46:46 PM) dholbach: back to sponsoring: sponsoring means: somebody who is in the ~ubuntu-dev signs your changes with their gpg key and uploads to the build daemon
(03:47:08 PM) dholbach: explains how it works
(03:47:20 PM) dholbach:  - basically you either work on an existing bug and follow up there or file a new one
(03:47:42 PM) dholbach:  -  you attach your debdiff (extra points if your changelog contains (LP: #123456) to fix the bug directly)
(03:48:05 PM) dholbach:  - you subscribe either ubuntu-universe-sponsors for universe/multiverse packages or
(03:48:11 PM) dholbach:  - you subscribe either ubuntu-main-sponsors for main/restricted packages
(03:48:12 PM) dholbach: done
(03:48:30 PM) dholbach: after a some time somebody will be in touch with you to review your patch and upload it once it's all good
(03:48:50 PM) dholbach: of course you wouldn't want to submit the colour/color debdiff, but do something useful instead ;-)
(03:49:08 PM) dholbach: and lists a lot of bugs to get started with
(03:49:13 PM) dholbach: my personal favourites are:
(03:49:28 PM) dholbach:  - bugs tagged as 'bitesize' (good for new contributors)
(03:49:43 PM) dholbach:  - bugs tagged as 'packaging' (bugs are in the packaging, not in the upstream source code)
(03:50:15 PM) dholbach:  - bugs that are fixed elsewhere (Launchpad has the nifty feature of indicating wether a bug is fixed upstream or in a different distro if you link to other bug trackers)
(03:50:26 PM) dholbach: those bugs should be a good start
(03:50:58 PM) dholbach: <pixelpapst> QUESTION: how would get this diff into my PPA ?
(03:51:35 PM) dholbach: pixelpapst: you'd        dput myppa xicc_0.2-2ubuntu1_source.changes        assuming that you have everything set up according to http:/
(03:51:44 PM) dholbach: <eddyMul> QUESTION: how to use LP to search for tags in bugs?
(03:52:00 PM) dholbach: eddyMul: the bugs should be linked from
(03:52:03 PM) dholbach: but hang on
(03:52:40 PM) dholbach:    should work too
(03:53:08 PM) dholbach: should have a lot of the information I just covered
(03:53:26 PM) dholbach: be bold, start fixing bugs, don't hesitate to ask in #ubuntu-motu or on ubuntu-motu-mentors@lists.u.c
(03:53:40 PM) dholbach: in addition to that we have a MOTU Q&A session every friday in this channel
(03:53:47 PM) dholbach: so there are lots of offers to help you get started
(03:54:23 PM) dholbach: more questions?
(03:55:35 PM) dholbach: If you like the event add your weblog to (by following the instructions on and blog about it or your progress on your MOTU Journey
(03:56:06 PM) dholbach: ok... if that's it... thanks everybody
(03:56:19 PM) shujin:  Thanks dholbach!
(03:56:20 PM) dholbach: I know you all can do it - hope to see you on your MOTU Journey soon :)
(03:56:21 PM) Solarion: dholbach: thanks
(03:56:26 PM) eddyMul: thanx, dholbach
(03:56:34 PM) awalton__: thanks
(03:56:37 PM) joumetal: thanks.
(03:56:38 PM) dholbach: hope to see you all tomorrow - the schedule is full with good stuff :)
(03:57:04 PM) barcc: dholbach: thanks
(03:57:13 PM) eddyMul: dholbach: hopefully no schedule switches.....
(03:57:15 PM) jcastro: thanks dholbach!
(03:57:27 PM) InsClusoe: Thanks a lot dholbach and all others who patiently explained the stuff and answered all our questions..

MeetingLogs/devweek0802/Debdiff1 (last edited 2008-08-06 16:36:14 by localhost)