Sample README.source

Debian policy 3.8.0 imposes that packages specify explicit how to apply their patches when using a patch system (cf. section 4.14 and http://lists.debian.org/…ce/2008/06/msg00001.html). The goal of this page is to propose some defaults for different patch systems.

Quilt

This package uses quilt in order to apply patches to the upstream source.  
Patches are stored in debian/patches. For further details, see the man page for 
quilt.

All commands described below should be run from the top directory of the 
package source tree, unless otherwise stated.

 * To generate the fully patched source, in a form ready for editing, that 
   would be built to create Debian packages, run: 
 
     export QUILT_PATCHES=debian/patches
     quilt push -a

 * To modify the source and save those modifications so that they will be 
   applied when building the package, pick a suitably informative patch file 
   name, for example Modify_README.source, and then run:

     export QUILT_PATCHES=debian/patches
     quilt new Modify_README.source
     quilt edit README.source

   This will place you in your default editor to modify the file.
   Once your are done editing, save the file and run:

     quilt refresh

 * To remove source modifications that are currently being applied when 
   building the package, run:

     export QUILT_PATCHES=debian/patches
     quilt top

dpatch

This package uses dpatch in order to apply patches to the upstream source.
Patches are stored in debian/patches and their filenames usually end in .dpatch .
For further details, see the man pages for dpatch and dpatch-edit-patch.

All commands described below should be run from the top directory of the 
package source tree, unless otherwise stated.

 * To generate the fully patched source, in a form ready for
   editing, that would be built to create Debian packages, run: 

     dpatch apply-all

   Note: This should happen automatically when you run 
   dpkg-source -x on a dpatch source package.

 * To modify the source and save those modifications so that
   they will be applied when building the package, pick a
   suitably informative patch file name, for example
   01_add_README.source_file.dpatch, and then run:

     dpatch-edit-patch 01_add_README.source_file.dpatch

   This will place you in a new shell in a temporary copy of the 
   source tree.  Make your desired modifications to it, and then 
   exit the shell to create the patch file containing them (this 
   file will appear in debian/patches).

 * To remove source modifications that are currently being
   applied when building the package, run:

     dpatch unapply-all

CDBS

This package uses CDBS (and therefore simple-patchsys.mk) in order to 
apply patches to the upstream source. Patches are stored in 
debian/patches and their filenames usually end in .patch or .diff .
For further details, see the man page for cdbs-edit-patch.

All commands described below should be run from the top directory of the 
package source tree, unless otherwise stated.

 * To generate the fully patched source, in a form ready for
   editing, that would be built to create Debian packages, run: 

     make -f debian/rules apply-patches

   Note: This should happen automatically when you run 
   dpkg-source -x on a CDBS simple-patchsys.mk source package.

 * To modify the source and save those modifications so that
   they will be applied when building the package, pick a
   suitably informative patch file name, for example
   01_add_README.source_file.patch, and then run:

     cdbs-edit-patch 01_add_README.source_file.patch

   This will place you in a new shell in a temporary copy of the 
   source tree.  Make your desired modifications to it, and then 
   exit the shell to create the patch file containing them (this 
   file will appear in debian/patches).

 * To remove source modifications that are currently being
   applied when building the package, run:

     make -f debian/rules reverse-patches