Patching a package

Make sure you have set up your environment.

Get the source

Download the source package

$ apt-get source my-program

and look for a diff.gz file. If that exists, then you're dealing with a non-native package, else it's a native package. A non-native package is software that comes from outside the distribution (e.g. from GNU). The original source is normally left untouched and changes happen with patch files. A native package comes from the distribution itself (e.g. debian-faq). There is no need to keep changes separate, so the source is edited directly.

Go into the source to start editing.

$ cd my-program-*

For native packages you can skip the next section and just start editing.

Non-native package

Migrate to quilt

Check if the package is using quilt to manage its patches.

grep -i quilt debian/source/format

If that file doesn't exist or the command has no output, then it's not using quilt. If there are no files in debian/patches then you can start using quilt directly (see next section), but first create the file debian/source/format if necessary and make sure it has exactly one line, saying:

3.0 (quilt)

If there are no patches then first try to convert from dpatch format.

dpatch2quilt.sh || echo not dpatch

If the format is not dpatch, then it's cdbs. Check if quilt support is enabled.

grep -E 'quilt.(mk|make)' debian/rules

If there's no output, then replace the following line near the top of debian/rules

include /usr/share/cdbs/1/rules/simple-patchsys.mk

with

include /usr/share/cdbs/1/rules/patchsys-quilt.mk

and add quilt to the list of Build-Depends in debian/control. Now make quilt aware of the existing patches.

quilt push -a

Using quilt

Start a new patch. We don't have a standard for patch names, but it's recommended to include some identification or short description of the problem or solution. In this case, it's the bug report number and a short problem description.

quilt new 654321_non-free_recommendation

and edit the necessary files:

quilt edit main.c

End the patch with a refresh:

quilt refresh

You should now have a .pc and debian/patches directory. If you don't, then check your ~/.quiltrc file and delete ~/.pc and ~/debian/changes if you have them.

See also Raphaël Hertzog's excellent summary about using quilt. Note that Parkes' quilt does not yet support the --dep3 option, so please refer to the DEP-3 format specification. It's good practice to add such a header to your patch.

Update the changelog

Debian provides a tool called dch to help ensure your changelog is valid.

$ dch -i

Briefly describe the change you made, with a reference to the bug report if it solves the problem. Also make sure to edit the version to indicate it has gNewSense changes. For example, if the suggested changelog entry looks like this:

my-package (1.0-2) unstable; urgency=low

  * 

 -- Joe Black <address@hidden>  Sat, 26 Jan 2013 15:27:52 +0100

Then our updated version will be something like:

my-package (1.0-1gnewsense1) parkes; urgency=low

  * Don't recommend non-free software. (Closes #123456)

 -- Joe Black <address@hidden>  Sat, 26 Jan 2013 15:27:52 +0100

Note that we don't have an unstable suite and use the name of the target suite instead. The version string should be identical to the last Debian version except for the gnewsense1 part.

Update the control file

The package should say that it is now maintained by gNewSense. Change the Debian information

...
Maintainer: Dave Smith <address@hidden>
Uploaders: Dave Smith
...
Vcs-Browser: http://git.debian.org/?p=pkg-xorg/xserver/xorg-server.git
Vcs-Git: git://git.debian.org/git/pkg-xorg/xserver/xorg-server
...

to the values for gNewSense.

...
Maintainer: gNewSense Hackers <address@hidden>
XSBC-Original-Maintainer: Dave Smith <address@hidden>
...
Vcs-Browser: http://bzr.savannah.gnu.org/lh/gnewsense/packages-parkes/my-package/
Vcs-Bzr: bzr://bzr.savannah.gnu.org/gnewsense/packages-parkes/my-package/
...

We always want to have our own Vcs-* fields, even if the file originally doesn't have them. Note that the Uploaders field has been deleted. We currently have no use for it.

README

Create a debian/README.gNewSense file that concisely describes why (and, if it took more than just a patch, how) the package was modified. You can also add any information you deem relevant, but can't fit anywhere else.

The debian/README.gNewSense file must follow the below format (sample):

Changed-From-Debian: A brief description of the change in a single line.
Change-Type: Modified

Longer description of the change is welcome. It can run into multiple lines. This long description can provide more comprehensive info about the details of the change or it might add notes that might be of interest to package wranglers or it might point to other places (like the changelog) where more information can be found.

The fields Changed-From-Debian & Change-Type can occur in any part of the file. The values of these fields can be optionally be formatted in MoinMoin wiki syntax.

Change-Type field can have one of these values — Modified, Added, Removed.

Build the package

First build the source package.

$ debuild -uc -us -S --lintian-opts --suppress-tags-from-file=$HOME/.lintiantags

This will also automatically run lintian to check for mistakes in your package. Also run lintian on the Debian source package

$ lintian my-package_1.0-1.dsc

and fix any warnings and errors that are different. You can get more details about the warnings with the -i option:

$ lintian -i my-package_1.0-1gnewsense1.dsc

If all is well then build the binary packages.

$ sudo aptitude build-dep my-package
$ debuild -uc -us -b

If that fails, fix your patch. If it succeeds, test the binaries by installing and running them.

Submit the patch

You can now reveal your fixed package to your fellow developers and submit it for inclusion in the package repository. Because the whole source package can be rather big, it is better to submit just the differences with the original. You can do this using debdiff.

$ cd ..
$ debdiff my-package_1.0-1.dsc my-package_1.0-1gnewsense1.dsc > my-package.diff

Attach my-package.diff to the bug report or send it to the gnewsense-dev mailing list.

CategoryDevelopment CategoryPackaging

From:	Sam Geeraerts
Subject:	Re: [Gnewsense-dev] Irssi bug #39251
Date:	Mon, 12 Oct 2015 23:55:47 +0200

Re: [Gnewsense-dev] Irssi bug #39251

Packaging for gNewSense

Introduction

Requirements

Environment setup

Packaging types

New package

Changing a package