# Notes on maintaining the stunnel source package

These are some notes related to the way the current maintainer,
Peter Pentchev, works on the package. They are not meant to be
normative, mandatory, or anything other than stating some personal
preferences and procedures.

## pristine-tar and gbp import-orig

Currently, the upstream source archive for stunnel is preserved using
the `pristine-tar` tool. The `debian/gbp.conf` file configures the various
`git-buildpackage` tools to honor that. Thus, the procedure for importing
a new upstream version is as follows:

- `uscan download` to obtain the new stunnel_*.orig.tar.gz and .asc files
- `gbp import-orig ../stunnel_VERSION.orig.tar.gz` - it should automatically
  also handle the pristine-tar branch and the signature file
- `git log pristine-tar` and `git show pristine-tar` just to make sure

## quilt for managing Debian-specific patches

The Debian-specific changes to stunnel are currently maintained using
the `quilt` tool and exported as patches in the `debian/patches/` directory.
Thus, the procedure for importing a new upstream version should then
continue as:

- `quilt push -a` to see whether the patches will apply cleanly
- `quilt push -f`, update patch files, `quilt refresh -p ab` repeatedly to
  update any patches that need refreshing because the upstream source files
  have changed
- `quilt delete ...` for any patches integrated upstream
- after each updated or removed patch, `quilt pop -a` and `quilt push -a` to
  get as far as we can
- after all the patches have been updated, refresh any line numbers by e.g.
  `quilt pop -a` and then `while quilt push; do quilt refresh -p ab; done`

## dgit push-source for new upstream releases

Since the `tag2upload` infrastructure does not currently handle `pristine-tar`
branches for new source tarballs, the `-1` revision for a new stunnel upstream
version should be uploaded using `dgit push-source`.

## dgit push-source or dgit debpush for other Debian revisions

The current maintainer has used `dgit push-source` for years now to manage
stunnel Debian package uploads. Nowadays `dgit debpush` may also be used in
accordance with https://wiki.debian.org/tag2upload

## debputy for the formatting of Debian package files

The files in the `debian/*` directory are formatted using the `debputy` tool
and its `black` source code formatting style as configured by
the `X-Style: black` source control field. 
After modifying a source file, run `debputy reformat` or use an editor's
LSP capabilities to get `debputy` to do that automatically.

There is also a `debputy-reformat` Salsa CI job that checks the formatting.

# debhelper compat level 14

This package uses the still-open-for-development compat level 14.
As documented in recent versions of `debhelper`, this is specified not by
the `debian/compat` file any more, but by the `X-DH-Compat` source control
field.
The use of a development compat level means that we cannot use
a `debhelper-compat (= 14)` virtual dependency, but must depend on
a specific `debhelper` version instead; the corresponding Lintian
diagnostics are overridden on purpose.
