Sample README.source

Use the official README.source files when they exist

This page is becoming obsolete. As of Ubuntu Jaunty Jackalope 9.04, instead of including a README.source file like these you can just point to the one provided within the /usr/share/doc/* tree:

• for dpatch use /usr/share/doc/dpatch/README.source.gz
• for quilt use /usr/share/doc/quilt/README.source
• for CDBS there does not seem to be an official included one yet

Background and Rationale

Debian policy 3.8.0 recommends that packages specify explicit how to apply their patches when using a patch system (cf. section 4.14 and http://lists.debian.org/debian-devel-announce/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: It has been proposed that in future, this should happen 
   automatically when you run dpkg-source -x on a dpatch source 
   package.  However, this proposal has apparently not yet been
   implemented, so for now you have to do it yourself like this.

 * 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 deapply-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: It has been proposed that, in future, this should happen 
   automatically when you run dpkg-source -x on a CDBS 
   simple-patchsys.mk source package.  However, this proposal has 
   apparently not yet been implemented, so for now you have to do 
   it yourself like this.

 * 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