--- /dev/null
+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. Please
+make sure to have the latest version of TopGit (>= 0.3) installed before
+trying this:
+
+1. Cloning the repository
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Cloning a TopGit repository requires an additional step to normal Git cloning:
+
+1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
+2. cd topgit
+3. tg remote --populate origin
+
+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. tg create stage-0.3-1 debian/locations
+ 2. git commit -m'staging 0.3-1'
+ 3. tg export --quilt debian/patches.new
+ 4. rm debian/patches.new/stage-*
+ 5. sed -i '/^stage-/d' debian/patches.new/series
+ 6. git checkout build && git rm -r debian/patches
+ 7. mv debian/patches.new debian/patches && git add debian/patches
+ 8. git commit -m'preparing 0.3-1'
+ 9. build, test, upload, tag ('debian/topgit-0.3-1')
+10. tg delete stage-0.3-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
+
+Now proceed as in the next step.
+
+6. Making changes to the master branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you make changes to the master branch (the "debianisation" branch), follow
+this procedure:
+
+1. tg summary
+2. for every branch that is prefixed with 'D' in the output:
+ git checkout $BRANCH && tg update
+3. git checkout build && git merge master
+
+7. 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
--- /dev/null
+This package was debianized by martin f. krafft <madduck@debian.org> on
+Mon, 11 Aug 2008 17:32:48 -0300.
+
+It was downloaded from <http://repo.or.cz/w/topgit.git>
+
+Upstream Author:
+
+ Petr Baudis <pasky@suse.cz>
+
+Copyright:
+
+ Copyright © 2008 Petr Baudis <pasky@suse.cz>
+
+License:
+
+ This package is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License.
+
+ This package is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this package; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+On Debian systems, the complete text of the GNU General
+Public License can be found in `/usr/share/common-licenses/GPL'.
+
+The Debian packaging is (C) 2008, martin f. krafft <madduck@debian.org> and
+is licensed under the GPL, see above.
~ian / topgit.git / commitdiff