[[custom]]
=== Customization of the Debian packaging

Let's recap the customization of the Debian packaging.

All customization data for the Debian package reside in the *debian/* directory.  A simple example is given in <<step-maintainer>>.  Normally, this customization involves combination of the followings:

* The Debian package build system can be customized through the *debian/rules* file (see <<customrules>>).
* The Debian package installation path etc. can be customized through the addition of configuration files in the *debian/* directory for the *dh_** commands from the *debhelper* package (see <<debianconf>>).

When these are not sufficient to make a good Debian package, the modification to the upstream source recorded as the *-p1* patches in the *debian/patches/* directory is deployed.  These patches are applied in the sequence defined in the *debian/patches/series* file before building the package (see <<patches>>).  A simple examples are given in <<alt-patch>>.

You should address the root cause of the Debian packaging problem by the least invasive way.  The generated package shall be more robust for the future upgrades in this way.

NOTE: Send the patch addressing the root cause to the upstream if it is useful to the upstream.

[[vcs]]
=== Recording in VCS (standard)

Typically, https://en.wikipedia.org/wiki/Git[Git] is used as https://en.wikipedia.org/wiki/Version_control[VCS] to record the Debian packaging activity with the following branches.

* *master* branch
** Record the source tree used for the Debian packaging.
** The upstream portion of the source tree is recorded unmodified.
** The upstream modifications for the Debian packaging are recorded in the *debian/patches/* directory as the *-p1* patches.
* *upstream* branch
** Record the upstream source tree untared from the released upstream tarball.

TIP: Its good idea to add the *.gitignore* file listing *.pc*.

TIP: Add *unapply-patches* and *abort-on-upstream-changes* to the *debian/source/local-options* file to keep the upstream portion unmodified

TIP: You may also track the upstream VCS data with a branch different from the *upstream* branch to ease cherry-picking of patches.

[[alt-vcs]]
=== Recording in VCS (alternative)

You may not wish to keep up with creating the *-p1* patch files for all upstream changes needed.  You can record the Debian packaging activity with the following branches.

* *master* branch
** Record the source tree used for the Debian packaging.
** The upstream portion of the source tree is recorded with modifications for the Debian packaging.
* *upstream* branch
** Record the upstream source tree untared from the released upstream tarball.

Adding few extra files in *debian/* directory enables you to do this.

-----
 $ tar -xvzf <package-version>.tar.gz
 $ ln -sf <package_version>.orig.tar.gz 
 $ cd <package-version>/
 ... hack...hack...
 $ echo "single-debian-patch" >> debian/source/local-options
 $ cat >debian/source/local-patch-header <<END
 This patch contains all the Debian-specific changes mixed
 together. To review them separately, please inspect the VCS
 history at https://git.debian.org/?=collab-maint/foo.git
-----

Let the *dpkg-source* command invoked by the Debian package build process (*dpkg-buildpackage*, *debuild*, ...) to generate the *-p1* patch file *debian/patches/debian-changes* automatically.

TIP: This approach can be adopted by any VCS tools.  If you wish to exclude VCS related files, please consider using *-I* and *-i* options for the *dpkg-source* command.

TIP: This approach is mean to be used with the public VCS.  Otherwise your patch becomes unreadable.

WARNING: The *debian/source/local-options* and *debian/source/local-patch-header* files are not included in the Debian source package and are meant to be recorded in VCS.

