Cyrus IMAPd - Debian source package documentation
-----------------------------------------------------

General guidelines:

This package has *all* changes from upstream stored into separate topic
patches.  This rule must be followed, even on NMUs.

The topic patches are managed by quilt, and follow the dpkg-source
format 3.0 (quilt) specification (see dpkg-source(1)).  THIS DOES NOT
MEAN THE PACKAGE MUST BE IN FORMAT 3.0 (quilt).  IT CAN ALSO HANDLE
FORMAT 1.0.

You MUST set the package format in debian/control, do NOT use
debian/source/format, or the -f switch to dpkg-source.  The Format:
header in debian/control overrides any other locations, and the 1.0
compatibility logic in the package only checks debian/control.

The package will make sure all patches are applied on build.  If you
want to build a Debian package with some patches unapplied, you will
have to use quilt to unapply them and *DISABLE* them in
debian/patches/series.

The package detects the current format from debian/control, and if it is
format 1.0, it will unapply all patches on the clean target.  Otherwise,
it will apply all patches on the clean target.

Note that changes to the packaging (debian/) are done directly, and
not through quilt patches.

This package will NOT build correctly unless the debian/rules "clean"
target is invoked first.  dpkg-buildpackage and all autobuilders do
this.

After you ran the clean target, you will get a work tree that is
suitable for Debian package builds through debian/rules.  IT WILL NOT
BUILD DIRECTLY.  CALL THE "build-prepare" TARGET IF YOU WANT IT IN A
DIRECTLY BUILDABLE STATE.

Do not patch autogenerated files, the build system will try very
hard to make your life miserable.   Fix the real bug.


Build workflow:

1. "clean" target will:
  - If a Makefile is available, attempt to call make distclean

  - Remove any target stamps (like the one for build-prepare)

  - Remove *all* autogenerated files, not just the autobuilt files, but
    also all of the autotoolization.  This *DOES* include the master
    Makefile, and configure scripts, as well as config.sub,
    config.guess, and a few others.  That's why the tree is not left in
    a buildable state.

  - Remove all auto-built files that came with the tarball, and all
    auto-built files which are part of the build system

  - For dpkg-source Format: 1.0
    - unapply any patches (otherwise, it will bloat the diff)

  - For dpkg-source Format: 3.0 (quilt)
    - apply all patches (as required by dpkg-source, although
      dpkg-source would try to fix this if we got it wrong)

  - remove anything else we change that must not leak to the
    diffs.

  We can't do much else here, or it will either leak crap to the diffs,
  or cause dpkg to abort due to unrepresentable changes to the source
  package.


2. "build-prepare" will:

  - Apply patches, if they are not already applied
    * The patches *ARE* allowed to update anything in the
      upstream buildsystem, such as Makefile.in, configure.in/ac,
      cmulocal/*, etc.

  - Rebuild the build system (autotoolize, etc)

  ALL standard build targets depend on build-prepare.

  We use automake because parts of automake are used by the system,
  even if automake is not used to generate Makefile.in

3. other useful auxiliary targets:
  - Target configure-stamp will be called to run ./configure with
    the proper options (and there are a *lot* of them).



Dealing with patches in debian/patch
------------------------------------

Use quilt.  It is reasonably smart, and will not easily leak crap into
the patches.  Please refer to quilt(1).  Make SURE you set
QUILT_PATCHES=debian/patches.  Make SURE you run quilt from the top
package directory (the one with the debian/ subdir).

If you need to temporarily disable patches for a build, make sure you
unapply them using quilt, and after that disable these patches in
debian/patches/series.

Use one patch per topic, not "per file".  Document the patch
throughoutly in the header.  Describe what it should be doing, and why
it needs to be done.

You can patch the build tree using the "patch" target, and unpatch it
using the "unpatch" target, or you can use quilt directly.


NMUs
----

Any and all changes to upstream code (i.e. any file outside of debian/)
*must* go in as a new quilt patch, or as an update to an existing quilt
patch.

Document new patches properly, both in the patch file headers and in the
Debian changelog.  Be verbose, terseness in changelogs is not only
overrated, it is outright hostile to long-term maintenance.

Always follow the current NMU procedures.

If the NMU is not an urgent upload or one approved beforehand, please
use the delayed upload queue to give us at least 5 days before it gets
installed.  Obviously, this does not apply to bin-NMUs.

 -- Ondřej Surý <ondrej@debian.org>, Wed, 17 Nov 2010 17:37:22 +0100
