#title Maintaining Debian Packages
#SORTtopics Debian; apt; dpkg; Git; GnuPG; lintian; Backports; DFSG
#lang en
#author Stefan Hornburg (Racke)

** Building from Git

More information in the [[https://wiki.debian.org/PackagingWithGit][Debian Wiki]].

<example>
gbp buildpackage
</example>

To use the command please install *git-buildpackage* package first.

Also setup the following environment variables (e.g. in =~/.bashrc=):

{{{
export DEBEMAIL="racke@linuxia.de"
export DEBFULLNAME="Stefan Hornburg (Racke)"
}}}

*** Invoking lintian after build

<example>
gbp buildpackage --git-postbuild='lintian -i $GBP_CHANGES_FILE'
</example>

This can be also configured in the configuration file =~/.gbp.conf=:

<example>
[DEFAULT]
postbuild=lintian -i $GBP_CHANGES_FILE
</example>

Note: =-i= shows detailed information about the lintian warnings and errors.

*** Build for release

With Git buildpackage command:

<example>
gbp buildpackage --git-pristine-tar --git-tag --changes-option=-S
</example>

With standard buildpackage  command:

{{{
dpkg-buildpackage --changes-option=-S
}}}

The =-S= option enables [[https://wiki.debian.org/SourceOnlyUpload][source-only upload]].
 
*** Integrating upstream release

Import the sources:

<example>
$ gbp import-orig --uscan
gbp:info: Launching uscan...
gbp:info: Using uscan downloaded tarball ../pure-ftpd_1.0.50.orig.tar.bz2
What is the upstream version? [1.0.50] 
gbp:info: Importing '../pure-ftpd_1.0.50.orig.tar.bz2' to branch 'upstream'...
gbp:info: Source package is pure-ftpd
gbp:info: Upstream version is 1.0.50
gbp:info: Replacing upstream source on 'master'
gbp:info: Successfully imported version 1.0.50 of ../pure-ftpd_1.0.50.orig.tar.bz2
</example>

If you use a DFSG repacked source:

<example>
$ gbp import-orig --uscan --pristine-tar --filter-pristine-tar
</example>

Also you need to make sure that you enter the appropriate
upstream version at the prompt:

<example>
gbp:info: Launching uscan...
uscan: Newest version of sympa on remote site is 6.2.22, local version is 6.2.20~dfsg
 (mangled local version is 6.2.20)
uscan:    => Newer package available from
      https://github.com/sympa-community/sympa/archive/6.2.22.tar.gz
gbp:info: using ../sympa_6.2.22.orig.tar.gz
What is the upstream version? [6.2.22] 6.2.22~dfsg
</example>

Add entry to =debian/changelog=:

<example>
sympa (6.2.66~dfsg-1) unstable; urgency=medium

  * New upstream release.

 -- Stefan Hornburg (Racke) <racke@linuxia.de>  Sat, 27 Nov 2021 14:26:58 +0100
</example>

Build:

<example>
$ gbp buildpackage
</example>

*** Branches

Dedicated branches are used for backports and also for bug fix releases
while working on packaging a new upstream release.

It is recommended to use the release in the branch name, e.g. *debian/buster*
or *debian/buster-backports*.

If you build from a dedicated branch, you need to tell that to *gbp*:

{{{
$ gbp buildpackage --git-debian-branch=debian/buster
}}}

*** Backports

Create a dedicated branch if you start a backport.

<example>
$ git checkout -b debian/stretch-backports
</example>

Otherwise update the branch:

<example>
$ git checkout debian/stretch-backports
$ git merge debian/6.2.24_dfsg-1
</example>

Resolve conflict in =debian/changelog=.

Build the package.

** Security bugs and uploads

Reference: [[https://www.debian.org/doc/manuals/developers-reference/pkgs.html#handling-security-related-bugs]]

** Building existing package from source

Install apt-src:

{{{
$ sudo apt install apt-src
}}}

Ensure that you have the proper sources in =/etc/apt/sources.list=, e.g.

{{{
deb-src http://ftp.de.debian.org/debian/ bullseye main
}}}

Create a directory and switch to it:

{{{
$ mkdir -p ~/debian/sympa
$ cd ~/debian/sympa
}}}

Retrieve source code

{{{
$ apt-src install sympa
}}}

Install build dependencies

<example>
$ sudo apt build-dep sympa
</example>

Build the package:

<example>
$ dpkg-buildpackage
</example>

** Upload packages to Debian

We are using the =dput= command for that. For a normal upload you need only pass
the name of the changes file:

{{{
$ dput ../sympa_6.2.66~dfsg-2_amd64.changes
}}}

#uploaddelayedqueue

A [[#nmu][NMU]] (non-maintainer upload) will be uploaded to the delayed queue:

{{{
$ dput --delayed=10 ../mhonarc_2.6.19-2.2_amd64.changes
}}}

** Files in =debian= directory

*** =changelog=

You can add a changelog entry based on your recent commit messages when you
are using =gbp=.

{{{
$ gbp dch
gbp:info: Found tag for topmost changelog version 'd9594474c2e98ea3165c0072427fa2f658caff5d'
}}}

*** =compat=

Specifies the debhelper compatibility level.

We recommend to use =13= as this level is supported in *buster-backports*.

You also need a corresponding entry in the =control= file:

{{{
Build-Depends: debhelper (>= 13), ...
}}}

*** =NEWS=

This file is designated for **important changes**
in a package.

The format is almost the same as for the =changelog= file, without the
asterisks in the content.
 
{{{
pure-ftpd (1.0.50-1) unstable; urgency=medium

  Support for MD5, SHA1 and MySQL PASSWORD() has been removed from password hashing.
  Please use scrypt, argon2 or the system crypt(3).

  The SPSV command has been removed.

 -- Stefan Hornburg (Racke) <racke@linuxia.de>  Sun, 28 Nov 2021 18:11:06 +0100
}}}
 
*** *package*.=default=

File with shell variables, which can be used in scripts or in systemd
units. Add *package* file to =/etc/default/=.

*** *package*.=dirs=

List of directories to create which are not installed by the build process.

*** *package*.=docs=

List of files to be installed into the =/usr/share/doc/*package*= directory.

*** *package*.=install=

Map of files and directories not installed by the build process for the
package.

*** *package*.=links=

List of symlinks to be added. Symlinks to a directory are not supported.

*** *package*.=logrotate=

Configuration file for logrotate tool. Adds *package* file to =/etc/logrotate.d=.

If you want to deviate from the default filename /etc/logrotate.d/*package*,
rename the file to *package*.*myname*.logrotate and and add the following
override to *rules*:

{{{
override_dh_installlogrotate:
	dh_installlogrotate --name myname
}}}

*** *package*.=pam=

Adds *package* file to =/etc/pam.d=.

If you want to put the PAM file under a different name, rename the file to
*package*.*myname*.pam and add the following override to *rules*:

{{{
override_dh_installpam:
	dh_installpam --name myname
}}}

*** =po=

This directory contains the translations for the Debconf templates.

***  =rules=

**** systemd

Installing systemd services where the main service triggers start of the
other services through *Wants* directive:

{{{
override_dh_installsystemd:
	dh_installsystemd --name sympa sympa.service
	dh_installsystemd --no-start --name sympa-bounced sympa-bounced.service
	dh_installsystemd --no-start --name sympa-archived sympa-archived.service
	dh_installsystemd --no-start --name sympa-bulk sympa-bulk.service
	dh_installsystemd --no-start --name sympa-task_manager sympa-task_manager.service
}}}

*** =source/format=

Indicates the source format.

Contents for regular package:

{{{
3.0 (quilt)
}}}

Contents for native package:

{{{
3.0 (native)
}}}

*** =templates=

This file contains the templates for Debconf.

*** =watch=

Contains specification for detecting new upstream releases.

Can be tested as follows:

{{{
uscan --no-download --verbose
}}}

Reference: [[https://wiki.debian.org/debian/watch]]


** Quilt

#quilt

[[https://raphaelhertzog.com/2012/08/08/how-to-use-quilt-to-manage-patches-in-debian-packages/][How to use quilt to manage patches in Debian packages]]

You need to **switch the current directory** before executing quilt commands,
otherwise the patches will end up in the wrong place.

{{{
$ cd debian/patches
}}}

You can also configure the directory for the patches in =~/.quiltrc=:

{{{
QUILT_PATCHES=debian/patches
}}}

*** Install quilt

{{{
$ sudo apt install quilt
}}}

*** Import existing patch

{{{
quilt import ~/downloads/tls1.3.patch
}}}

*** Update patch

Upstream changed a patch which already exists in =debian/series=.

In order to update the patch, follow this example:

{{{
$ quilt push backtick-syntax-1087.diff
Applying patch backtick-syntax-1087.diff
patching file src/lib/Conf.pm

Now at patch backtick-syntax-1087.diff
$ git checkout src/lib/Conf.pm
Updated 1 path from the index
$ patch -p 1 < backtick-syntax-1087.diff 
patching file src/lib/Conf.pm
$ quilt refresh
Refreshed patch backtick-syntax-1087.diff
$ quilt pop
Removing patch backtick-syntax-1087.diff
Restoring src/lib/Conf.pm

No patches applied
$ git add debian/patches/backtick-syntax-1087.diff
$ git commit -m "Update backtick-syntax patch from upstream."
[master 36760b9] Update backtick-syntax patch from upstream.
 1 file changed, 6 insertions(+), 8 deletions(-)
}}}

*** Remove patch

You can remove your patch =tls1.3.patch= in case it has been incorporated into a new
upstream release.

{{{
quilt delete -r tls1.3.patch
}}}

Example for corresponding git commit:

{{{
git add debian/patches
git commit -m "Remove TLS1.3 compatibility fix which is included in the 1.0.48 release."
}}}

** Debconf template translations

 - Add or update the PO file (e.g. =sv.po= fo Swedish) in =debian/po= directory
 - Run =debconf-updatepo= program as the translator may have used an outdate
   PO file

** Non-maintainer upload (NMU)
#nmu

In a nutshell, do the following steps:

 - Fix bug with minimal changes
 - Use version number with extra digit (2.6.19-2.1 as NMU for 2.6.19-2)
 - Add changelog entry "Non-maintainer upload" or "NMU"
 - Build the package
 - Use =nmudiff= to update bug report
 - Upload package to [[#uploaddelayedqueue][delayed queue]]

** Manipulating bugs through email

Replace *xxxxxx* with the actual bug number in the following examples
and send these in the body of an email to =control@bugs.debian.org=.

Reference: [[https://www.debian.org/Bugs/server-control]]

To close a bug, you can write an email to *xxxxxx*=-done@bugs.debian.org=.
It is recommended to add a pseudo header with the package version that fixed
the bug:

{{{
Version: 6.2.18~dfsg-1
}}}

*** Mark bug as confirmed

<example>
tags xxxxxx + confirmed
</example>

*** Change title of the bug

<example>
retitle xxxxxx Foo is not Bar
</example>

*** Other versions

{{{
found 939636 6.2.40~dfsg-2
}}}

*** Add usertags for Bug squashing party

<example>
user debian-release@lists.debian.org
usertag xxxxxx  + bsp-2018-12-ch-bern
</example>

** pbuilder

Setup pbuilder for a specific distribution:

<example>
DIST=jessie git-pbuilder create
</example>

Building for a specific distribution:

<example>
gbp buildpackage --git-pbuilder --git-dist=jessie
</example>

** Review contents of a package

<example>
dpkg -c /home/racke/build/debaux/debaux_0.1.11-1_all.deb
</example>

** Debugging

*** Debconf

You can set the environment variable *DEBCONF_DEBUG* in order to debug the interaction with Debconf during package installation.

<example>
export DEBCONF_DEBUG=developer
</example>

** Resources

[[https://wiki.debian.org/BuildingTutorial][Debian Building Tutorial]]

[[https://wiki.debian.org/DFSGLicenses][DFSG Licenses]]