## page was renamed from PackagingGuide/README.source
= 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. [[http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource|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
}}}