Add debian/README.source

Well, see the text inside. ;-)

diff --git a/debian/README.source b/debian/README.source
new file mode 100644 (file)
index 0000000..f3ded1d
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,95 @@
+Xen packaging for Debian
+========================
+
+Step 1: Get the upstream source
+-------------------------------
+
+The upstream Xen source code is not included with the packaging code
+repository.
+
+When doing additional work on a new debian revision of an existing package for
+a specific upstream version, grab the orig tar that's already in the package
+archives and put it just outside the directory of this repository.
+
+To package a new upstream version, an orig tar can be generated by pointing the
+genorig.py progam to your local xen git repository.
+
+Clone the upstream git repository somewhere (not inside the packaging
+directory, somewhere else!):
+
+    -$ git clone https://xenbits.xen.org/git-http/xen.git
+
+After cloning it, do:
+    -$ debian/bin/genorig.py /path/to/xen/repo
+
+Based on the version number in the newest debian/changelog entry, a release tag
+or specific commit will be used to generate the orig tar file. For now, see
+commit 55129e390c in this repository, "debian/lib/python: Recognize pre / rc
+versions" about more information.
+
+Example: If the latest entry in changelog is 4.10.0-1, then this will build the
+orig tar from the RELEASE-4.10.0 tag in upstream git:
+
+    -$ debian/bin/genorig.py ~/src/git/xen
+    Generate tarball ../orig/xen_4.10.0.orig.tar.xz
+
+Step 2: Combine the upstream source and packaging
+-------------------------------------------------
+
+The orig target in debian/rules is our friendly helper here:
+
+    -$ debian/rules orig
+    mkdir -p ../orig
+    tar -C ../orig -xaf ../xen_4.10.0.orig.tar.xz
+    rsync --delete --exclude /debian --exclude .git -a ../orig/xen-4.10.0/ .
+    QUILT_PATCHES='[...]/debian/patches' QUILT_PC=.pc quilt push --quiltrc - -a -q --fuzz=0
+    Applying patch version.diff
+    Applying patch config-prefix.diff
+    [...]
+    Applying patch tools-xentoolcore-abiname.patch
+    Now at patch tools-xentoolcore-abiname.patch
+
+Step 3: Generate missing packaging files
+----------------------------------------
+
+Quite some files in the packaging are generated. At least all the files which
+have version-dependent names etc.
+
+To generate them:
+
+    -$ debian/rules debian/control
+    /usr/bin/make -f debian/rules debian/control-real
+    make[1]: Entering directory '[...]'
+    debian/bin/gencontrol.py
+    md5sum debian/changelog [...] > debian/control.md5sum
+
+    This target is made to fail intentionally, to make sure
+    that it is NEVER run during the automated build. Please
+    ignore the following error, the debian/control file has
+    been generated SUCCESSFULLY.
+
+    exit 1
+    debian/rules:79: recipe for target 'debian/control-real' failed
+    make[1]: *** [debian/control-real] Error 1
+    make[1]: Leaving directory '[...]'
+    debian/rules:69: recipe for target 'debian/control' failed
+    make: *** [debian/control] Error 2
+
+This looks a bit wonky, but it makes sure we're not able to do the actual
+package build without having taken this step.
+
+Step 4: Build the package
+-------------------------
+
+Use your favourite way to build the package. Mine is pbuilder, so I'm doing
+something like
+
+    -$ pdebuild --use-pdebuild-internal \
+      --auto-debsign --debsign-k ABCDEF \
+      --configfile /home/knorrie/.pbuilderrc-sid
+
+Step 5: Cleanup and reset everything
+------------------------------------
+
+To cleanup the whole packaging environment, just do a git clean -dfx, and
+you're ready to continue back at step 2.