IncorporatingUpstreamChanges

Dev Week -- Incorporating upstream changes in Ubuntu -- cyphermox -- Tue, Jan 31st, 2012

   1 [21:31] <cyphermox> Hi and welcome to my session!
   2 [21:31] <cyphermox> My name is Mathieu Trudel and I'm a developer in the Ubuntu Desktop team. Some of the things I'm known for touching are NetworkManager and Evolution :)
   3 [21:31] <cyphermox> I'll be talking about incorporating upstream changes in Ubuntu. This is something we do relatively often in order to fix bugs that are discovered.
   4 [21:32] <cyphermox> Since I'm part of the Ubuntu Desktop team, I'll focus on some of the ways we deal with such a task in the team. There are usually slightly different workflows depending on the teams, but most of it comes down to the same.
   5 [21:32] <cyphermox> I'll go relatively quick for the first part, and answers questions at the end.
   6 [21:32] <cyphermox> If you miss anything, don't worry, it's all right here: http://people.ubuntu.com/~mathieu-tl/presentations/incorporating_changes_into_Ubuntu.txt
   7 [21:32] <cyphermox> There are at least three ways by which you can incorporate upstream changes in Ubuntu:
   8 [21:33] <cyphermox> 1) Taking an brand new version (with a very different version number, or just a "bugfix" release)
   9 [21:33] <cyphermox> I'll actually let coolbhavi talk about this; he has a session tomorrow, Wednesday Feb 2nd, at 16:00 UTC where he would be covering that. (It's called "How to update a package to the latest upstream version in the repositories")
  10 [21:33] <cyphermox> In reality, it's the "simplest" way, where you'd upgrade the package to a newer upstream version directly, in the case where that fixes bugs and doesn't have too high a risk of introducing new ones.
  11 [21:34] <cyphermox> 2) Taking a "snapshot" of an upstream source repository.
  12 [21:34] <cyphermox> This is similar to taking a brand new version. In this case, you would use packaging tools to generate a new upstream tarball to be used as your "new upstream version". For instance, gnome-pkg-tools knows how to grab source from a git tree.
  13 [21:34] <cyphermox> Some packages use this often, but as a general rule of thumb, we try to avoid it: using a snapshot of upstream code has a pretty high chance of also including bugs that haven't been discovered or fixed yet. The reason why is pretty simple: if it's not released yet, it's probably still a work in progress.
  14 [21:34] <cyphermox> All in all though, the process is the same as for a new upstream release, with the added step that you need to make your own tarball.
  15 [21:35] <cyphermox> and... Any questions so far?
  16 [21:35] <cyphermox> I'll just assume not and carry on
  17 [21:36] <cyphermox> 3) Cherry-picking patches from upstream.
  18 [21:36] <ClassBot> TiMiDo asked: what's the difference between ubuntu-devel and ubuntu-motu teams?
  19 [21:38] <cyphermox> TiMiDo: there isn't much of a difference, really. the Ubuntu-devel channel and the Ubuntu developers team in general is a superset of all the various development teams. Everybody is interested in development. Then the ubuntu-motu team and channel have a bit more of a specialist task, where they'd look after packages in universe, or unseeded packages, which is a whole lot of things we get from Debian but for which
  20 [21:38] <cyphermox> there isn't necessarily someone looking after on a day to day basis
  21 [21:38] <cyphermox> I guess this would be my response
  22 [21:39] <cyphermox> MOTU is also a great place to ask for help if you're starting to learn about packaging
  23 [21:39] <cyphermox> We now get to the main subject, a demo of how one would integrate upstream changes (in the form of a patch) into Ubuntu.
  24 [21:40] <cyphermox> Patches can come from a variety of sources: you could write your own, get it from a bug report upstream, or from a bug report against Fedora, or from Debian. To demonstrate how we would do this, I've chosen an example task. We'll fix a small bug in Evolution, everybody's favorite mail client :)
  25 [21:41] <cyphermox> I'll take that opportunity to plug the Operation Cleansweep, also know as the Ubuntu Review team. They look at the quality of patches attached to bugs in Launchpad. I haven't prepared anything about this really, but you're welcome to ask me about it. That's who looks at the patch, patch-submitted-upstream, etc. tags on bugs
  26 [21:41] <cyphermox> back to preparing a patch...
  27 [21:42] <cyphermox> there's a few key things you'll need first
  28 [21:42] <cyphermox> - a system running Precise. sorry, I really planned my demo around this, though in reality it's really not a very different process
  29 [21:43] <cyphermox> - the branch for Evolution (more on this in a minute)
  30 [21:43] <cyphermox> - build-dependencies for evolution (I'll get to that as well, but if you want to get started: "sudo apt-get build-dep evolution")
  31 [21:44] <cyphermox> - and you'll also need bazaar, and the builddeb plugin to bazaar ("sudo apt-get install bzr bzr-builddeb").
  32 [21:44] <cyphermox> With a bit of luck I'm not forgetting any of the pieces :)
  33 [21:44] <cyphermox> For this, you'll need to have a copy of the evolution packaging branch, which is maintained by the Ubuntu Desktop team. On a fast system, this only takes a few seconds:
  34 [21:44] <cyphermox> bzr branch lp:~ubuntu-desktop/evolution/ubuntu evolution
  35 [21:45] <cyphermox> This command basically downloads the source for the evolution package from Launchpad.
  36 [21:45] <cyphermox> The next step is to get in that directory. You'll notice it only contains a debian/ directory, which is a slightly different, but similar process from using UDD branches (full package branches, coming from lp:ubuntu/package or ubuntu:package, when it's not maintained elsewhere).
  37 [21:47] <cyphermox> For full package branches (UDD branches), barry will be doing a session about this tomorrow, Wed Feb 1, at 19:00 UTC
  38 [21:47] <cyphermox> The process is pretty similar, with the difference that the branch contains both the debian/ directory and the full source code for the package
  39 [21:47] <cyphermox> The way to know what branch to use is generally to rely on the Vcs-Bzr field in the debian/control file. Unfortunately, that field isn't always present or pointing to the right place, and isn't obvious to see before downloading the source anyway. Fortunately, the 'debcheckout' command helps with that.
  40 [21:47] <cyphermox> debcheckout evolution
  41 [21:48] <cyphermox> Would yield the same result as the previous command I suggested. If it's not done downloading, let it run, we'll look at other things in the meantime :)
  42 [21:48] <cyphermox> As a next step, let's go see what kind of bug we could fix: https://bugs.launchpad.net/evolution/+bug/924356
  43 [21:48] <cyphermox> everybody got this far?
  44 [21:49] <cyphermox> I've opened this one myself. There's an associated upstream bug (https://bugzilla.gnome.org/show_bug.cgi?id=651221) which was opened by somebody else, and it's actually fixed in a commit upstream. We can then go take that patch and include it in the package.
  45 [21:49] <cyphermox> Now, the bug report mentions two things: one is an actual patch that we could probably take immediately since it's most likely what was committed, as well as a commit ID. We can get to this commit id: http://git.gnome.org/browse/evolution/commit/?id=3dc8b0b
  46 [21:49] <cyphermox> (I'm obviously talking about the Gnome Bug report here)
  47 [21:50] <cyphermox> Looking back at the bug report however, it's mentioned being for 3.3.5 and above, in git branch "master"... This won't affect us now, but sometimes patches for different versions than what we're using could take substancial amounts of rework to apply properly.
  48 [21:50] <ClassBot> There are 10 minutes remaining in the current session.
  49 [21:50] <cyphermox> Save the patch (click "(patch)" near the top of the commit page, then Save As), with a name that will make sense to you and to others. The cool thing with this particular form of patch is that it already contains tags along the top that identify its provenance, and is already in the right format to be saved directly in the debian/patches/ directory. This is possible because the evolution package uses quilt to
  50 [21:50] <cyphermox> maintain patches.
  51 [21:51] <cyphermox> As a general rule I try to make it clear that a patch from a git tree comes from a git tree, and where exactly it comes from. This one, I'd name something like "git_edit_new_default_email_3dc8b0b.patch". Note the reuse of the commit ID, just so that it's as clear as possible where this comes from.
  52 [21:51] <cyphermox> When comes time to update the package to a new version, it's (hopefully) easier to tell that a patch coming from git can probably be simply dropped, since it will already have been included in the new release.
  53 [21:52] <cyphermox> Continuing... In an ideal world there isn't much left to do, but sometimes patches don't quite apply right, or need a bit of changes to do the right thing. Let's see how it goes and add its name to the end of the file 'debian/patches/series'. (Assuming you're in the package's directory)
  54 [21:52] <cyphermox> echo "git_edit_new_default_email_3dc8b0b.patch" >> debian/patches/series
  55 [21:52] <cyphermox> Because we're working in version control, we really also need to add the patch file to version control:
  56 [21:52] <cyphermox> bzr add debian/patches/git_edit_new_default_email_3dc8b0b.patch
  57 [21:52] <cyphermox> And we'll also add an entry to changelog to describe what we've been doing and to close the bug report. This is usually done using the 'dch' or 'debchange' command; and with the -i switch, which adds a new entry. If you try this now though, you'd see that it adds a new entry, however there's one under it marked UNRELEASED. This is because I had already started work on that package :)
  58 [21:53] <cyphermox> Let's use "dch -a" instead. A new entry will be added under mine, normally with your name in brackets just above it.
  59 [21:53] <cyphermox> Add the information about what we've done. We've added a file, so let's name it, and explain what it does and close the bug, all that beside the *:
  60 [21:53] <cyphermox> debian/patches/git_edit_new_default_email_3dc8b0b.patch: use an account's
  61 [21:53] <cyphermox> associated email address rather than the default address when editing new
  62 [21:53] <cyphermox> messages. (LP: #924356)
  63 [21:53] <cyphermox> Try your best to limit the lines to 80 characters and align the start with the other lines. With this done, let's try to test build the package (you need bzr-builddeb for that, and the build dependencies for evolution, so let's get all of this too)!
  64 [21:54] <cyphermox> sudo apt-get install bzr-builddeb
  65 [21:54] <cyphermox> sudo apt-get build-dep evolution
  66 [21:54] <cyphermox> bzr bd
  67 [21:54] <cyphermox> Bzr-builddeb will try to build the package, starting with getting the source tarball for you from the archive. If all goes well, you'd have a .deb package at the end of this to use to test your own work.
  68 [21:55] <cyphermox> I'll take questions again. Don't forget to add QUESTION:  before it, it helps a lot to make sure I see it :
  69 [21:55] <ClassBot> There are 5 minutes remaining in the current session.
  70 [21:56] <cyphermox> Once this is done, you'd go ahead and test the same build in a pbuilder or schroot after building a source package (bzr bd -S); and if that goes well too you could commit your changes, release the package, and submit a merge proposal or upload.
  71 [21:56] <cyphermox> debcommit       # commit my changes
  72 [21:56] <cyphermox> dch -r          # release to precise (all this does is change UNRELEASED to precise and update the timestamp)
  73 [21:56] <cyphermox> debcommit -r    # commit the release
  74 [21:56] <cyphermox> These are the three steps condensed in commands
  75 [21:57] <cyphermox> With this done, you could push the branch to your launchpad account (name it something that makes sense to you, but it should be under your launchpad ID, and in the evolution project):      bzr push lp:~yourname/evolution/lp924356
  76 [21:57] <cyphermox> And propose a merge:         bzr lp-propose lp:~ubuntu-desktop/evolution/ubuntu
  77 [21:57] <cyphermox> From there, a developer will be able to review your changes and upload them.
  78 [21:58] <cyphermox> I can go in more details for anyone who asks, I don't think there's another session next :)
  79 [22:00] <cyphermox> Thanks all for attending! :)
  80 

MeetingLogs/devweek1201/IncorporatingUpstreamChanges (last edited 2012-02-01 12:56:50 by dholbach)