<> <> = Simple bug fix example using 'git', 'bzr' and 'edit-path' = <> = Some prerequisites = You'll need some tools, and also the build depends for scribus. Next two commands takes care of this: $ sudo apt-get install ubuntu-dev-tools git devscripts $ sudo apt-get build-dep scribus = Fixing the Bug = This example shows how to fix a bug in an Ubuntu package consisting of upstream source, meaning not an Ubuntu Studio original package with Ubuntu Studio original source. To fix bugs in Ubuntu Studio original source packages, you simply add the fix to the source and it will be available in the current development release. To add the fix to a stable release package, however, the process may be close to what we do in this example. In this example, a desktop file is missing from the package called [[https://launchpad.net/ubuntu/+source/scribus|scribus]], and we want to fix that. Here's the bug report: https://bugs.launchpad.net/ubuntu/+source/scribus/+bug/1487031 == About the package and the circumstances == This package is not packaged by Ubuntu developers, but by Debian developers, and is imported from Debian to Ubuntu. Since the bug involves the packaging itself, the bug should be fixed in Debian first, and then in Ubuntu - if needed. In our case, the Debian package has been fixed, but since we have reached DebianImportFreeze, we didn't automatically get the fix into the latest Ubuntu development release, currently Wily, and so we need to patch the package with the fix. == Get the repositories and find the fix == === Get the Debian git repo === We will first get the debian git repo which has the fix we want The tool we use is called '''git'''. The git command '''clone''' will copy the git repository from the url we specify, and the last argument '''scribus-debian''' is what we name the folder where the git repo ends up being copied to. Omitting '''scribus-debian''' will name the folder by it's default name '''scribus'''. But, we don't want that, since later we are getting another repo also named scribus, and we want to be able to tell them apart. So, this is the command for getting scribus from the debian repository: $ git clone https://anonscm.debian.org/git/collab-maint/scribus.git scribus-debian === Get the Ubuntu bzr repo === Now we need to get the Ubuntu repo which we intend to patch with our fix. The procedure is pretty much the same, though it is a bazaar repo, and we use the tool '''bzr''' instead of '''git'''. Also the url looks different. '''ubuntu:scribus''' is shorthand for the package '''scribus''' within the '''ubuntu''' launchpad project. You can also replace '''ubuntu:scribus''' with '''lp:ubuntu/scribus''', which is the same thing. $ bzr branch ubuntu:scribus scribus-ubuntu === Find the fix in the debian repo === Now we cd into the debian repo, and check to see which commit has the fix we want using the command "git log" (we could do a search, but let's keep it simple for now). $ cd scribus-debian $ git log Reading through the log, we find a commit with this commit message: debian/scribus{,-data}.install: install the .desktop file in /usr/share/applications in the scribus binary" Above it we see the commit id: commit 0f3a7ac3af72dac5a4270fa32497072315751ee2 ...which is what we need if we want to see the actual commit and the changes it made. Now, quit git log by pressing "q" (for quit), and run the next command to show the commit in question: $ git show 0f3a7ac3af72dac5a4270fa32497072315751ee2 We see a diff, that looks like this: ---- {{{ Author: Mattia Rizzolo Date: Wed Jun 3 03:02:50 2015 +0200 debian/scribus{,-data}.install: install the .desktop file in /usr/share/applications in the scribus binary Closes: #795705 diff --git a/debian/scribus-data.install b/debian/scribus-data.install index 7454ad6..b86761a 100644 --- a/debian/scribus-data.install +++ b/debian/scribus-data.install @@ -7,6 +7,5 @@ usr/share/doc/scribus/TODO usr/share/doc/scribus/TRANSLATION usr/share/man usr/share/mime -usr/share/mimelnk usr/share/scribus usr/share/scribus/icons/scribus.png usr/share/pixmaps/ diff --git a/debian/scribus.install b/debian/scribus.install index 527b78f..5389e5a 100644 --- a/debian/scribus.install +++ b/debian/scribus.install @@ -1,2 +1,3 @@ usr/bin usr/lib +usr/share/mimelnk/application/vnd.scribus.desktop usr/share/applications }}} ---- === Analyzing the commit with the fix === Two files have been changes. The file ''debian/scribus-data.install'' and ''debian/scribus.install''. Both are debian package files that install certain files during the installation of the packages '''scribus-data''' and '''scibus''', both which originate from this same source. Since our bug only involves '''scribus''' and its desktop file, we can see that all we need to do is add a line to the file ''scribus.install'', namely: usr/share/mimelnk/application/vnd.scribus.desktop usr/share/applications We can't just change the ubuntu package, as that could potentially mess up the source for future fixes. We need to add a patch to it, so that the patch can easily be removed, or changed in the future, if needed. So, the next step is to create the patch. == Create a patch for scribus == First, make sure you are in the Ubuntu scribus repo. So: $ cd ../scribus-ubuntu We use the tool '''edit-patch''' to create the patch. What it does is it records any changes you made to the debian package, and then stores those in a patch which ends up in the dir ''debian/patches''. '''edit-patch''' takes one argument - the name of the patch you are going to create. So, something like this: $ edit-patch missing-desktop-file-fix.patch Now, you can make changes to the source. Open the file ''debian/scribus.install'': $ nano debian/scribus.install And, add the line mentioned before: usr/share/mimelnk/application/vnd.scribus.desktop usr/share/applications Ok, you're done making changes. Let's finish up the patch by closing edit-patch using '''Ctrl+D'''. This will create the debian/patches/patch (and some other changes), and opens ''debian/changelog'' in your chosen cli text editor. Adjust ''debian/changelog'' to contain the correct info. Rename ''RELEASE'' to the release in question (wily, in this case), and describe what the patch does. It's usually enough just to add the bug that it fixes (which launchpad will automatically recognize). This is the result: {{{ scribus (1.4.5+dfsg1-1ubuntu1) wily; urgency=medium * debian/patches/missing-desktop-file-fix.patch: (LP: #1487031) }}} Now, we can close the text editor. I use '''nano''', so for me it's '''Ctrl+X'''. Next, we get a question. Answer '''no''' to it, since we need to make some more changes before we commit this patch. OK to commit? [Y/n/e] n Just to see what has happened so far, you can let bzr show you the diff: $ bzr diff You'll see a bunch of files that have changed. This is what will be included in the bzr commit. === Document the patch === We still need to edit the patch description to document what it does and why. So, open your patch with your text editor of choice: $ nano debian/patches/missing-desktop-file-fix.patch At the top, you see a header, looking something like this: {{{ ## Description: add some description ## Origin/Author: add some origin or author ## Bug: bug URL }}} Follow the [[http://dep.debian.net/deps/dep3/|Debian Patch Tagging Guidelines]] on what to add. Also, see http://packaging.ubuntu.com/html/patches-to-packages.html on how to patch Ubuntu packages specifically. We need the tag ''Bug-Ubuntu'' in this case. So, the end result might look something like this: ---- {{{ ## Description: Fixes missing desktop file ## Origin/Author: Kaj Ailomaa ## Bug-Ubuntu: https://bugs.launchpad.net/ubuntu/+source/scribus/+bug/1487031 ## Forwarded: not-needed --- a/debian/scribus.install +++ b/debian/scribus.install @@ -1,2 +1,3 @@ usr/bin usr/lib +usr/share/mimelnk/application/vnd.scribus.desktop usr/share/applications }}} ---- That's it. Next, we commit, test build, and upload our package with the fix. === Commit the changes === Now, we can commit the changes, using the command '''debcommit'''. $ debcommit By this time, all changes are committed in our local repository, and we can test build. = Doing a test build = If you haven't already, get the build requisites for scribus: $ sudo apt-get build-dep scribus Get the original source for this package, from the the ''scribus-ubuntu'' dir: $ bzr get-orig-source Build the package with '''bzr-buildpackage''' $ bzr-buildpackage