Add test scenario for multi-repository project

2 files changed, 139 insertions, 1 deletions

diff --git a/doc/070-pipeline.yarn b/doc/070-pipeline.yarn
index 037d4a2..db4048c 100644
--- a/doc/070-pipeline.yarn
+++ b/doc/070-pipeline.yarn
@@ -4,7 +4,12 @@ This chapter describes how to actually use Ick to build Debian
 packages. We'll use Ick to actually build a toy package. This assumes
 we have the necessary access to localhost.
 
-    SCENARIO build Debian packages
+## Single repository and branch ("a la liw")
+
+First, we'll do a simple case where the Debian packaging and the
+upstream source code are kept in one repository and branch.
+
+    SCENARIO build Debian packages from one branch
 
 First of all, we need a git repository with some source code.
 
@@ -45,6 +50,81 @@ Then we do the build.
 As a result, there's several resulting packages that should exist.
 First of all, a CI build for unstable:
 
+    THEN the APT repository for foo.ick contains
+    ... foo_3.2.0ci1-1.unstable.dsc
+    THEN the APT repository for foo.ick contains
+    ... foo_3.2.0ci1-1.unstable_all.deb
+
+We tag a release and build it. Because our test package is
+architecture independent, there aren't versions for each architecture
+separately.
+
+    GIVEN a git tag foo-3.2 on tip of master in foo
+    WHEN user runs ick foo.ick
+    THEN the APT repository for foo.ick contains foo_3.2-1.dsc
+    THEN the APT repository for foo.ick contains foo_3.2-1_all.deb
+    THEN the APT repository for foo.ick contains foo_3.2-1.debian8.*.dsc
+    THEN the APT repository for foo.ick contains foo_3.2-1.debian8.*_all.deb
+
+## Separate repositories for upstream code and package ("a la Daniel")
+
+Some people prefer to keep Debian packaging and upstream code
+entirely separate. In this case, the repository with packaging
+contains only the packaging, and it contains the contents of the
+`debian` directory, not the directory itself. In other words, the
+repository contains `changelog` and `rules`, not `debian/changelog`
+and `debian/rules`.
+
+To accomodate this, Ick allows a project to specify any number of git
+repositories and branches that are stitched together to form a source
+tree.
+
+    SCENARIO build Debian packages from separate repositories
+
+First of all, we need a git repository with some upstream source code,
+but no packaging, and a separate repository with the corresponding
+packaging.
+
+    GIVEN an upstream source repository for project foo
+    AND a packaging repository called deb for project foo version 3.2
+
+Then we need an Ick file.
+
+    GIVEN an ick file foo.ick containing
+    ... {
+    ...     "state": "foo.state",
+    ...     "targets": {
+    ...         "ci_unstable": {
+    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
+    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
+    ...         },
+    ...         "release_jessie": {
+    ...             "address": "$ICK_JESSIE_TEST_TARGET",
+    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
+    ...         },
+    ...         "release_unstable": {
+    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
+    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
+    ...         }
+    ...     },
+    ...     "projects": {
+    ...         "foo": {
+    ...             "gits": [
+    ...                 { "git": "foo", "branch": "master", "root": "." },
+    ...                 { "git": "deb", "branch": "master", "root": "debian" }
+    ...             ],
+    ...             "pipelines": ["debian-ci", "debian-release"]
+    ...         }
+    ...     }
+    ... }
+
+Then we do the build.
+
+    WHEN user runs ick foo.ick
+
+As a result, there's several resulting packages that should exist.
+First of all, a CI build for unstable:
+
     THEN the APT repository for foo.ick contains 
     ... foo_3.2.0ci1-1.unstable.dsc
     THEN the APT repository for foo.ick contains 
diff --git a/doc/900-implements.yarn b/doc/900-implements.yarn
index 28db6b7..29f5ca2 100644
--- a/doc/900-implements.yarn
+++ b/doc/900-implements.yarn
@@ -128,6 +128,64 @@ the master branch as well.
     git add debian
     git commit -m "Add Debian packaging"
 
+Create repository with just upstream code.
+
+    IMPLEMENTS GIVEN an upstream source repository for project (\S+)
+    gitdir="$DATADIR/$MATCH_1"
+    git init "$gitdir"
+    cd "$gitdir"
+    echo "This is $MATCH_1" > README
+    git add README
+    git commit -m "Add README"
+
+    printf '#!/bin/sh\necho hello, world\n' > hello
+    chmod +x hello
+    git add hello
+    git commit -m "Add hello"
+
+Create a git repository with just Debian packaging files.
+
+    IMPLEMENTS GIVEN a packaging repository called (\S+) for project (\S+) version (\S+)
+
+    gitdir="$DATADIR/$MATCH_1"
+    PROJECT="$MATCH_2"
+    VERSION="$MATCH_3"
+
+    git init "$gitdir"
+    cd "$gitdir"
+
+    mkdir source
+    echo '3.0 (quilt)' > source/format
+    echo Public domain > copyright
+    echo 9 > compat
+    echo hello usr/bin > install
+
+    export DEVSCRIPTS_CHECK_DIRNAME_LEVEL=0
+    dch --create --package "$PROJECT" --newversion "$VERSION" \
+        -c changelog "Initial version."
+    dch -c changelog -r ''
+
+    cat << EOF > control
+    Source: $MATCH_1
+    Maintainer: John Doe <john@example.com>
+    Section: python
+    Priority: optional
+    Standards-Version: 3.9.6
+    Build-Depends: debhelper (>= 7.3.8)
+
+    Package: $MATCH_1
+    Architecture: all
+    Depends: \${misc:Depends}
+    Description: this is a test package
+     Test package is this.
+
+    EOF
+
+    printf '#!/usr/bin/make -f\n%%:\n\tdh $@\n' > rules
+    chmod +x rules
+
+    git add .
+    git commit -m "Add Debian packaging"
 
 ## Running "cleanly"