A broad overview is presented here for the basic rules of Debian packaging focusing on the non-native Debian package in the ``*3.0 (quilt)*'' format.

NOTE: Some details are intentionally skipped for clarity.  Please read the manpages of the *dpkg-source*(1), *dpkg-buildpackage*(1), *dpkg*(1), *dpkg-deb*(1), *deb*(5), etc.

The Debian source package is a set of input files used to build the Debian binary package and is not a single file.

The Debian binary package is a special archive file which holds a set of installable binary data with its associated information.

A single Debian source package may generate multiple Debian binary packages defined in the *debian/control* file.

The non-native Debian package in the ``*3.0 (quilt)*'' format is the most normal Debian source package format.

NOTE: There are many wrapper scripts.  Use them to streamline your workflow but make sure to understand the basics of their internals.

[[workflow]]
=== Packaging workflow

The Debian packaging workflow to create a Debian binary package involves generating several specifically named files (see <<name-version>>) as defined in the ``Debian Policy Manual''.

The oversimplified method for the Debian packaging workflow can be summarized in 10 steps as follows.

1. The upstream tarball is downloaded as the 'package-version'**.tar.gz** file.
2. The upstream tarball is untarred to create many files under the 'package-version'**/** directory.
3. The upstream tarball is copied (or symlinked) to the particular filename 'packagename_version'**.orig.tar.gz**.
* the character separating 'package' and 'version' is changed from *-* (hyphen) to *_* (underscore)
* *.orig* is added in the file extension.
4. The Debian package specification files are added to the upstream source under the 'package-version'**/debian/** directory.
* Required specification files under the *debian/* directory:
*debian/rules*::
The executable script for building the Debian package (see <<rules>>)
*debian/control*::
The package configuration file containing the source package name, the source build dependencies, the binary package name, the binary dependencies, etc. (see <<control>>)
*debian/changelog*::
The Debian package history file defining the upstream package version and the Debian revision in its first line (see <<changelog>>)
*debian/copyright*::
The copyright and license summary (see <<copyright>>)
* Optional specification files under the *debian/** (see <<debianconf>>):
* The *debmake* command invoked in the 'package-version/' directory provides the initial set of these template configuration files.
** Required specification files are generated even with the *-x0* option.
** The *debmake* command does not overwrite any existing configuration files.
* These files must be manually edited to their perfection according to the ``Debian Policy Manual'' and ``Debian Developer's Reference''.
5. The *dpkg-buildpackage* command (usually from its wrapper *debuild* or *sbuild*) is invoked in the 'package-version/' directory to make the Debian source and binary packages by invoking the *debian/rules* script.
* The current directory is set as: *$(CURDIR)=*'/path/to/package-version/'
* Create the Debian source package in the ``*3.0 (quilt)*'' format using *dpkg-source*(1)
** 'package_version'.*orig.tar.gz* (copy or symlink of 'package-version'.*tar.gz*)
** 'package_version-revision'.*debian.tar.xz* (tarball of 'package-version'/*debian/**)
** 'package_version-revision'.*dsc*
* Build the source using ``*debian/rules build*'' into *$(DESTDIR)*
** *DESTDIR=debian*/'binarypackage/' (single binary package)
** *DESTDIR=debian/tmp/* (multi binary package)
* Create the Debian binary package using *dpkg-deb*(1), *dpkg-genbuildinfo*(1), and *dpkg-genchanges*(1).
** 'binarypackage_version-revision_arch'.*deb*
** ... (There may be multiple Debian binary package files.)
** 'package_version-revision_arch'.*changes*
** 'package_version-revision_arch'.*buildinfo*
6. Check the quality of the Debian package with the *lintian* command. (recommended)
* Follow the rejection guidelines from https://ftp-master.debian.org/[ftp-master].
** https://ftp-master.debian.org/REJECT-FAQ.html[REJECT-FAQ]
** https://ftp-master.debian.org/NEW-checklist.html[NEW checklist]
** https://ftp-master.debian.org/#lintianrejects[Lintian Autorejects] (https://ftp-master.debian.org/static/lintian.tags[lintian tag list])
7. Test the goodness of the generated Debian binary package manually by installing it and running its programs.
8. After confirming the goodness, prepare files for the normal source-only upload to the Debian archive.
9. Sign the 'package_version-revision'.*dsc* and 'package_version-revision'_*source.changes* files with the *debsign* command using your private GPG key.
10. Upload the set of the Debian source package files with the *dput* command to the Debian archive.

Test building and confirming of the binary package goodness as above is the moral obligation as a diligent Debian developer but there is no physical barrier for people to skip such operations at this moment for the source-only upload.

Under some exceptional situation such as NEW uploads, uploads to the Debian archive may need to include Debian binary package files.
For such situation, sign 'package_version-revision_arch'.*changes* instead of 'package_version-revision'_*source.changes* in the step 9, and upload the set of the Debian source and binary package files in the step 10.

Here, please replace each part of the filename as:

* the 'package' part with the Debian source package name
* the 'binarypackage' part with the Debian binary package name
* the 'version' part with the upstream version
* the 'revision' part with the Debian revision
* the 'arch' part with the package architecture

See also https://wiki.debian.org/SourceOnlyUpload[Source-only uploads].

TIP: Many patch management and VCS usage strategies for the Debian packaging are practiced.  You don't need to use all of them.

TIP: There is very extensive documentation in https://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html[Chapter 6. Best Packaging Practices] in the ``Debian Developer's Reference''.  Please read it.

[[debhelper]]
==== The *debhelper* package

Although a Debian package can be made by writing a *debian/rules* script without using the *debhelper* package, it is impractical to do so.  There are too many modern ``Policy'' required features to be addressed, such as application of the proper file permissions, use of the proper architecture dependent library installation path, insertion of the installation hook scripts, generation of the debug symbol package, generation of package dependency information, generation of the package information files, application of the proper timestamp for reproducible build, etc.

*Debhelper* package provides a set of useful scripts in order to simplify Debian's packaging workflow and reduce the burden of package maintainers. When properly used, they will help packagers handle and implement ``Policy'' required features automatically.

The modern Debian packaging workflow can be organized into a simple modular workflow by:

* using the *dh* command to invoke many utility scripts automatically from the *debhelper* package, and
* configuring their behavior with declarative configuration files in the *debian/* directory.

You should almost always use *debhelper* as your package's build dependency. This document also assumes that you are using a fairly contemporary version of *debhelper* to handle packaging works in the following contents.

[[historical-perspective]]
=== Historical perspective of Debian packaging practices

Let me oversimplify historical perspective of Debian packaging practices.

https://www.debian.org/doc/manuals/project-history/index.en.html[Debian was started in 1990s] when upstream packages were available from public FTP sites such as https://en.wikipedia.org/wiki/Sunsite[Sunsite].
In those early days, Debian packaging used dpkg-source currently known as "`Format: 1.0`":

* Upstream released packages in tar.gz format.  They were obtained from some FTP sites.
* Debian applied "one big patch" as its source distribution and made its binary distribution form it.
* Many different approaches were adopted by different Debian developers to manage topic patches with custom scripts within the "one big patch". -- Chaos!

In order to address issues of old dpkg-source "`Format: 1.0`", new dpkg-source "`Format: 3.0 (quilt)`" was invented around 2008:

* Upstream released packages in tar.gz/tar.bz2/tar.xz format optionally with signature files.  They were obtained from some HTTP sites.
* Most Debian developers adopted patch queue mechanism of "`Format: 3.0 (quilt)`" to manage topic patches and made Debian packages while keeping files outside of `debian/` directory untouched.
* VCS, especially git, became popular and most Debian developers and started to record this packaging practice in `gbp-buildpackage`(1) style.
* The `gbp-buildpackage`(1) workflow records the exact same content of the upstream tarball to VCS for source files outside of `debian/` directory (= patch-unapplied).

The use of Git repositories to distribute upstream packages with signed tags (supported feature since 2011) became very popular.

* The tarball centric `gbp-buildpackage`(1) workflow to record changes to VCS was cumbersome for some Debian developers and `dgit`(1) was invented in 2013.
* The Git centric `dgit-maint-debrebase`(7) and `dgit-maint-merge`(7) workflows to record changes to VCS are gaining popularity among these Debian developers.
* Source files recorded to VCS by `dgit-maint-debrebase`(7) and `git-maint-merge`(7) are modified upstream source files (= patch-applied).
* Uploaded source packages by `dgit-maint-debrebase`(7) and `git-maint-merge`(7) workflows still use dpkg-source "`Format: 3.0 (quilt)`".

Debian also enforced the source-only upload when developing Debian/11 Bullseye (released in 2021).

In this tutorial, mostly simple tarball based dpkg-source "`Format: 3.0 (quilt)`" examples are presented as an introductory purpose.

Please asses these VCS usage approaches by yourself later to decide which one to deploy as your preferred one.

[[future-perspective]]
=== Future perspective on Debian packaging practices

Please look around to understand how Debian packaging practices are evolving and follow the current general trends if possible.

* https://dep-team.pages.debian.net/[DEP - Debian Enhancement Proposals]
** Debian Enhancement Proposals (or DEPs, for short) offer a device to organize discussions about various kinds of enhancements in the Debian project, reflect their current status and, in particular, archive their outcomes.
* https://trends.debian.net/[Debian Trends]
** This page provides some historical perspective about how those practices evolved.
* https://wiki.debian.org/GitPackagingSurvey[Debian git packaging maintainer branch formats and workflows]
** Nice packaging summary by the latest `dgit` tool providers.

You can also search entire Debian source code by yourself, too.

* https://sources.debian.org/[Debian Sources] -- code search tool
** https://wiki.debian.org/DebianCodeSearch[Debian Code Search] -- wiki page describing its usage
* https://dcs.zekjur.net/[Debian Code Search] -- another code search tool
