debian/patches

This page stemmed from the following discussion on debian-devel in January 2008: <alpine.DEB.1.00.0801250818360.5187@wr-linux02>. It also includes ideas from the discussion #250202 about the Policy.

Note: The patch format itself is now a formal DEP, DEP-3: Patch Tagging Guidelines.

Existing systems

General characteristics

Patch system

Status

Location of the patches

How to deactivate a patch

Accepts diff -u output

Advantage

3.0 (quilt)

supported

debian/patches in .debian.tar.gz file

Rename to include a non-word non-hyphen character

Yes

Native to dpkg as 3.0 (quilt) format

quilt

supported

debian/patches

Remove its name from debian/patches/series

Yes

Suitable for generating patches on any size codebase. Advanced VCS-like features.

cdbs simple-patchsys

deprecated

debian/patches

Remove its .diff or .patch suffix

Yes

Simple

2.0 a.k.a. wig&pen

obsolete (use 3.0 quilt)

debian/patches in .debian.tar.gz file

Rename to include a non-word non-hyphen character

Yes

Native to dpkg as 2.0 format

dpatch

obsolete

debian/patches

Remove its name from debian/patches/00list

Header needs to be added

Can do scripting

dbs

obsolete

debian/patches

Remove it from the directory

Yes

Patches applied in ASCIIbetical order, no series file. Tarball-in-tarball (if you're in to that).

Packages using dpatch system can be converted easily to quilt system which has better supports by other software, e.g. guilt for git.

Patching/unpatching targets includible in debian/rules

Thanks to the cooperation of the maintainers of dpatch, quilt and CDBS, patch and unpatch targets became standard.

File

Package

To patch

To unpatch

/usr/share/dpatch/dpatch.make

dpatch

patch

unpatch

/usr/share/quilt/quilt.make

quilt

patch

unpatch

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

quilt

patch

unpatch

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

cdbs

patch

unpatch

/usr/share/cdbs/1/rules/dpatch.mk

cdbs

patch

unpatch

Note that in the case of quilt it may be better to use $(QUILT_STAMPFN) since patch is a phony target.

Limitations

Users of a source package need the unpacked source not ready for compilation, but ready for inspection and modification. The two major use cases are application of (minor) local modifications (security fixes, compile time options) and manual or automated inspection of the source code (auditing, searching). This should be possible without installing additional packages besides dpkg-dev.

It has been discussed that the use of patch systems was making the work of porters, NMUers, security and QA teams difficult for several reasons:

  1. The profusion of patch systems. People would have to learn them all and to be able to detect which one is used in the package they are working on.
  2. The difficulty to repack the sources. If direct modifications of source packages block the target unpatch, and if this target is called by clean, dpkg-buildpackage will fail.

  3. This approach is not compatible with the 3.0 (quilt) format.

  4. Documents such as /usr/share/doc/debian/source-unpack.txt do not warn that modifications to the freshly unpacked sources can break the patching step.

Proposed improvements

Rejected ideas

Using a VCS (instead of patch system) to track changes

Keeping a whole package, including upstream sources, in a version control system (VCS) is often used as a method of managing the modification to upstream sources.

Comparison between the two paradigms

debian/patches

VCSes

Changes to upstream sources are divided in logical blocks that are the patches.

Changes to upstream sources are divided into logical blocks that are groups of commits.

dpkg-buildpackage can fail after modifications of the sources

dpkg-buildpackage can not be blocked by the impossibility to unpatch the sources.

The diff.gz file only contains files located in the debian directory

Informations conveyed by defining groups of commits is not reflected in the diff.gz file.

Well documented in beginners tutorials, strong tradition in packaging teams.

No tutorials for beginners, new and not widespread yet.

Repositories can be limited to contain only the debian directory.

Need to keep the upstream sources in a VCS as well. Not true in my experience. What's the justification for this assertion? --BenFinney

Some systems, such as dpatch allow scripting.

Changes are systematically applied.

Of course, the use of VCS have other advantages, but this table focuses on the perspective of their substitution to patch management systems.

Previous unanswered questions

Current situation

At the time of dpkg 1.14.17 release, 3.0 format was included and Bugs: 4588 et. al. was closed.


CategoryDebianDirectory | CategoryPackaging