HACKING: Document git use and release process

1 files changed, 76 insertions, 2 deletions

diff --git a/HACKING b/HACKING
index 04d4f0ac..e460c154 100644
--- a/HACKING
+++ b/HACKING
@@ -5,6 +5,26 @@ This document is a short guide to the conventions used in the schroot
 project.
 
 
+Building from git
+-----------------
+
+First, clone the git repositories:
+
+% git clone git://anonscm.debian.org/git/buildd-tools/schroot
+% cd schroot
+% git remote add origin-dist git://anonscm.debian.org/git/buildd-tools/schroot-dist
+% git fetch origin-dist
+% ./bootstrap
+
+schroot.dist is only required if you want to run "make dist-git"; this
+repository is where the distribution branches are stored (from which
+the distribution tarballs are created with "git archive").  See
+"Releasing", below.
+
+./bootstrap is required to bootstrap the autotools.  Once this is done,
+you can run ./configure just like from the release tarball.
+
+
 Coding
 ------
 
@@ -66,8 +86,10 @@ The following styles are used:
 Releasing
 ---------
 
-The code must pass the testsuite (make check).  It must also pass some
-tests which must be run by hand:
+The code must pass the testsuite:
+% make check
+
+It must also pass some tests which must be run by hand:
 
 Chdir fallback behaviour:
 
@@ -83,3 +105,55 @@ Setup script behaviour:
 
   To check if process killing works:
   schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 20 &"
+
+In order to make a release, the following must be done:
+
+* Use a fresh clone or make sure the tree is pristine, including
+  the debian directory (make sure it does not contain any build
+  material, which could be packaged if present).
+* Make sure all generated files are up to date.  Run "make dist"
+  and/or "make -C po update-po" to update all translations.
+  Commit any changes.
+* Ensure that the distribution branch is branched locally.  For
+  example, if making a 1.6.x release, checkout
+  origin-dist/distribution-1.6 as distribution-1.6 e.g.
+
+  % git checkout -b distribution-1.6 origin-dist/distribution-1.6
+
+  If this is the first release in a stable series, e.g. 1.6.0,
+  the local branch will be created automatically.
+* Make the release:
+
+  % make release-git ENABLE_RELEASE_GIT=true
+
+  You will be prompted for your GPG key passphrase in order to
+  sign the release tag (release/schroot-$version).
+* Rebootstrap and reconfigure:
+
+  % ./bootstrap
+  % ./config.status --recheck
+  % make
+
+  This will ensure the release metadata in VERSION is up to date (it's
+  generated from the release tag).  Double check that there are no
+  modifed files.  If there are, delete the release tag and start again.
+* Make the distribution:
+
+  % make dist-git ENABLE_DIST_GIT=true
+
+  You will again be prompted for your GPG key passphrase, to sign the
+  distribution tag (distribution/schroot-$version).  This will also
+  inject the distributed release onto the distribution-x.y branch.
+  Verify with "gitk distribution-x.y" that the distribution is sane,
+  and ties in sanely with the previous distributions and releases.  If
+  there's a mistake, delete the distribution tag and reset --hard the
+  distribution-x.y branch to its previous state.
+* Make the distributed release tarball:
+  git archive --format=tar --prefix=schroot-$version/ distribution/schroot-$version | xz --best > schroot-$version.tar.xz
+  This creates a tarball from the release tag.
+* Push all branches and tags to the correct places:
+
+  % git push origin $branch
+  % git push origin release/schroot-$version
+  % git push origin-dist distribution-x.y
+  % git push origin-dist distribution/schroot-$version