Patching a package

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.

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:

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

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.