From: martin f. krafft <madduck@debian.org>
Date: Tue, 12 Aug 2008 17:33:09 +0000 (-0300)
Subject: add instructions for building from source
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topgit.git;a=commitdiff_plain;h=7bbd3df2fec411ca68412c6a9df875829466f867

add instructions for building from source

Signed-off-by: martin f. krafft <madduck@debian.org>
---

diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644
index 0000000..077a583
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,7 @@
+topgit for Debian
+-----------------
+
+TopGit is itself managed with TopGit. Per Debian policy, have a look into
+README.source to see how this is done.
+
+ -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..7c5104b
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,97 @@
+Building topgit for Debian
+--------------------------
+
+The topgit source package  uses quilt to apply and remove its patches. Please
+refer to /usr/share/doc/quilt/README.source for information about how to use
+quilt for source packages.
+
+The quilt series is, however, generated from the Git repository, using TopGit
+itself. While subject to change, this currently happens as follows:
+
+1. Branches in use
+~~~~~~~~~~~~~~~~~~
+The following branches are in use in the package:
+
+- upstream: tracks the upstream Git repository
+- fixes/*: patches fixing problems with upstream
+- features/*: patches providing new features, targetted upstream
+- master: the main Debianisation branch
+- debian/*: Debian-specific patches
+
+upstream and master are regular Git branches, while the others are TopGit
+branches. The reason why master is not a TopGit branch itself is so that it's
+possible to export all TopGit-managed branches into the quilt series, without
+having to make an exception for master.
+
+2. Developing a new feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to develop a new feature (or bug fix), first consider whether the
+patch is intended to go upstream or is a Debian-specific change. Choose the
+namespace accordingly and base it off upstream or master respectively. If the
+patch depends on another patch, obviously base it off the respective TopGit
+branch.
+
+The following are the steps required to add a feature branch/patch:
+
+1. tg create features/new-feature upstream
+   - or -
+   tg create debian/new-debian-stuff master
+
+2. edit .topmsg and make the subject line be a short description, optionally
+   add a longer description to the body
+
+3. git add .topmsg && git commit -m'create branch features/new-feature'
+
+3. Obtaining the upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The upstream tarball for $VERSION can be obtained using pristine-tar:
+
+  pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
+
+4. Building the package
+~~~~~~~~~~~~~~~~~~~~~~~
+To build the package, you check out the build branch, recreate debian/patches,
+commit, build, test, upload, tag:
+
+ 1. git checkout build && git rm -r debian/patches
+ 2. tg create stage-0.2-1 fixes/destdir debian/locations ...
+ 3. git commit -m'staging 0.2-1'
+ 4. tg export --quilt debian/patches
+ 5. rm debian/patches/stage-*
+ 6. sed -i '/^stage-/d' debian/patches/series
+ 7. git checkout -f build && git add debian/patches
+ 8. git commit -m'preparing 0.2-1'
+ 9. build, test, upload, tag ('debian/topgit-0.2-1')
+10. tg delete stage-0.2-1
+
+This process is still very cumbersome and needs to be improved, ideally within
+TopGit.
+
+5. Importing a new upstream version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To import a new upstream, pull it into the upstream branch, merge upstream
+into the master branch, ideally together with an update to debian/changelog,
+then update all TopGit branches:
+
+1. git checkout upstream
+2. git pull
+3. git checkout master
+4. git merge upstream
+5. tg summary
+6. for every branch that is prefixed with 'D' in the output:
+     git checkout $BRANCH && tg update
+
+6. Building an upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Until upstream provides official tarballs, the following can be used to create
+them for Debian:
+
+1. git archive --prefix=$(git describe upstream)/ --verbose upstream \
+    | gzip -9 > ../$(git describe upstream | sed s,-,_,).orig.tar.gz
+2. pristine-tar commit ../$(git describe upstream | sed s,-,_,).orig.tar.gz \
+    upstream
+
+All comments and suggestions are welcome, especially those pertaining to
+auto-generating debian/changelog from commit logs.
+
+ -- martin f. krafft <madduck@debian.org>  Mon, 11 Aug 2008 17:32:48 -0300
diff --git a/debian/docs b/debian/docs
index e845566..0da37bf 100644
--- a/debian/docs
+++ b/debian/docs
@@ -1 +1,2 @@
 README
+debian/README.source