# The `cleanly` helper tool

The Debian package build pipeline contains a number of steps. To allow
the steps to be easily combined and reordered, the are not integrated
deeply into the Ick program, but provided by a separate helper program
instead, called `cleanly`. This de-couples the pipeline and Ick, and
allows the pipeline to be used with other CI systems as well. This
section describes how `cleanly` works.

## Extract project metadata

The first thing we need to do is determine, preferably automatically,
what the name of the project is and what its version is.

    SCENARIO cleanly performs pipeline steps
    GIVEN a source code repository for project foo version 3.2-1

    WHEN user runs, in foo,
    ... cleanly --ci --buildno 1 --debian-release debian7 get-name
    THEN the output is "foo\n"

In CI mode, we want the upstream version number to be mangled, by
appending the current build number. This avoids having to rely on the
developers to update the version number diligently. For cleanly to do
this, we need to tell it the build number.

    WHEN user runs, in foo,
    ... cleanly --ci --buildno=5 --debian-release=debian8 get-upstream-version
    THEN the output is "3.2.0ci5\n"

In release build mode, however, we want no mangling.

    WHEN user runs, in foo,
    ... cleanly --release --debian-release debian8 get-upstream-version
    THEN the output is "3.2\n"

## Create upstream release tar archive

We create a tar archive by extracing the source code from git. For CI
builds, the mangled upstream version is used. Note how the mangled
upstream version gets `.0ci{buildno}` appended to it: the `.0` is to
make sure the mangled version comes after `3.2` but before `3.2.1`
using Debian version comparison semantics.

    WHEN user runs, in foo,
    ... cleanly --ci --buildno 42 --debian-release=debian7 tarball
    THEN file foo-3.2.0ci42.tar.xz exists

For release builds, it's the declared upstream version.

    WHEN user runs, in foo,
    ... cleanly --release --debian-release debian7 tarball
    THEN file foo-3.2.tar.xz exists

## Create Debian source package

Next up is the Debian source package. We assume the upstream project
provides the Debian packaging files in the same branch. Since we're
doing a CI build, the upstream version number gets mangled and the
Debian version is always just 1 with the target's Debian release
appended.

    WHEN user runs, in foo,
    ... cleanly --ci --buildno 42 --debian-release debian7 
    ... --debian-codename unstable dsc
    THEN file foo_3.2.0ci42.orig.tar.xz exists
    AND file foo_3.2.0ci42-1.debian7.debian.tar.xz exists
    AND file foo_3.2.0ci42-1.debian7.dsc exists

For a release build, once again, no version mangling. (Boring to read?
Imagine how boring this is to write. I need writing lessons.)

Actually, that's a lie. The release build _will_ mangle versions, by
adding the upload target's release number to the Debian part of the
full version number. This is so that we can build an upstream version
separately for each supported Debian release (e.g., Debian 7 and 8).

    WHEN user runs, in foo,
    ... cleanly --release --debian-release debian7 dsc
    THEN file foo_3.2.orig.tar.xz exists
    AND file foo_3.2-1.debian7.debian.tar.xz exists
    AND file foo_3.2-1.debian7.dsc exists

However, if the release name is `unstable`, no mangling should happen.
(Really.)

    WHEN user runs, in foo,
    ... cleanly --release --debian-release unstable dsc
    THEN file foo_3.2.orig.tar.xz exists
    AND file foo_3.2-1.debian.tar.xz exists
    AND file foo_3.2-1.dsc exists

## Build a Debian binary package

This is where things get interesting. We build a Debian binary
package, given a source package. (Note that for this scenario, we fake
the actual build to avoid having to have `root` access.)

    WHEN user runs, in foo,
    ... cleanly --test-mode --ci --buildno 42 --debian-release debian7 deb
    THEN file foo_3.2.0ci42-1.debian7_all.deb exists

Similarly in release builds.

    WHEN user runs, in foo,
    ... cleanly --test-mode --release --buildno 42 --debian-release debian7 deb
    THEN file foo_3.2-1.debian7_all.deb exists

    WHEN user runs, in foo,
    ... cleanly --test-mode --release --buildno 42 --debian-release unstable deb
    THEN file foo_3.2-1_all.deb exists