--- /dev/null
+Using TopGit to generate quilt series for Debian packaging
+----------------------------------------------------------
+
+You have been referred to this document probably because a source package you
+are working on uses TopGit to generate a quilt series to encapsulate
+differences between upstream and the source code used for the Debian package.
+
+Please make sure that you have a recent version of TopGit (>= 0.5) installed
+before trying any of this.
+
+Where appropriate, the examples use the topgit package itself to illustrate
+the use. I trust you to be able to make the appropriate amendments for your
+situation.
+
+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
+
+You can also use the debcheckout tool from the devscripts package:
+
+ debcheckout topgit
+
+which will do all the above for you automatically.
+
+Branches in use
+'''''''''''''''
+The following branches are in use in the topgit package. You are free to
+deviate from this set for the package you are working on, but then please
+document it accordingly in your README.source.
+
+- 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
+
+3. Obtaining the upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The upstream tarball for the topgit package $VERSION can be obtained using
+pristine-tar:
+
+ pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
+
+4. Building the package
+~~~~~~~~~~~~~~~~~~~~~~~
+Building the package is trivial, thanks to the inclusion of the tg2quilt.mk
+snippet at the top of debian/rules.
+
+Unless you set the TG_BRANCHES variable before the include statement (or when
+you invoke debian/rules (or make), tg2quilt will simply export all TopGit
+branches into the quilt series. You can set the variable TG_BRANCHES to
+a space- or comma-separated list (but not comma and space) of feature branches
+to export, e.g.:
+
+ TG_BRANCHES := branch1,branch2
+ TG_BRANCHES := 'branch3 branch4 branch 5'
+
+Building the package requires no additional steps over other Debian packages.
+
+Since it is currently not possible to access TopGit branches for previous
+versions of a package (#500656), it is a good idea to maintain a build branch,
+into which you merge the master (Debianisation) branch whenever making a new
+release, and where you simply track the contents of the debian/patches
+directory. This can conveniently become the branch from which you build:
+
+1. git checkout build
+2. git merge master
+3. ./debian/rules tg-export
+4. git add debian/patches
+5. git commit -m'preparing $VERSION'
+6. build, test, upload, tag ('debian/topgit-$VERSION')
+
+TODO: add a debian/NEWS entry to get people to switch to using this approach.
+
+5. Importing a new upstream version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To import a new upstream, update the remote, merge the tag you want to merge
+into the master branch, ideally together with an update to debian/changelog,
+then update all TopGit branches:
+
+1. git remote update
+2. git checkout master
+3. git merge <new-upstream-tag>
+
+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
+
+7. Building an upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you are using pristine-tar, the follopwing can be used to commit an
+upstream tarball to the repository. It makes sense to rename it according to
+the Debian-standard package_version.orig.tar.gz convention first.
+
+1. pristine-tar commit ../topgit_$VERSION.orig.tar.gz <upstream-tag>
+
+If upstream does not provide tarballs, you can create the orig.tar.gz file and
+commit is as follows:
+
+1. git checkout topgit-$VERSION
+2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
+ | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
+3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
+ HEAD
+4. git checkout master
+
+
+
+All comments and suggestions are welcome, especially those pertaining to
+auto-generating debian/changelog from commit logs.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:16:03 +0100
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.5) installed before
-trying this:
+The quilt series is generated from the Git repository, using TopGit itself.
+This process is documented in /usr/share/doc/topgit/HOWTO-tg2quilt.
-1. Cloning the repository
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Cloning a TopGit repository requires an additional step to normal Git cloning:
+The topgit packages uses the branch layout described in the aforementioned
+document.
-1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
-2. cd topgit
-3. tg remote --populate origin
-
-You can also use the debcheckout tool from the devscripts package:
-
- debcheckout topgit
-
-which will do all the above for you automatically.
-
-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 are encouraged to include the TopGit make snippet at
-the top of debian/rules:
-
- -include /usr/share/topgit/topgit.mk
-
-This will provide the tg-export target, which will create a quilt series of
-all TopGit branches in the current repository.
-
-You can also set the variable TG_BRANCHES before the inclusion to a space- or
-comma-separated list (but not comma and space) of feature branches to export,
-e.g.:
-
- TG_BRANCHES := branch1,branch2
- TG_BRANCHES := 'branch3 branch4 branch 5'
-
-(The TopGit package actually uses the local version of the file)
-
-When you are ready to build, you check out the build branch, recreate
-debian/patches, commit, build, test, upload, tag:
-
-1. git checkout build
-2. git merge master
-3. ./debian/rules tg-export
-4. git add debian/patches
-5. git commit -m'preparing 0.5-1'
-6. build, test, upload, tag ('debian/topgit-0.5-1')
-
-TODO: add a debian/NEWS entry to get people to switch to using this approach.
-
-5. Importing a new upstream version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To import a new upstream, update the remote, merge the tag you want to merge
-into the master branch, ideally together with an update to debian/changelog,
-then update all TopGit branches:
-
-1. git remote update
-2. git checkout master
-3. git merge topgit-0.5
-
-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
-
-7. Building an upstream tarball
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Until upstream provides official tarballs, the following can be used to create
-them for Debian:
-
-1. git checkout topgit-0.5
-2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
- | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
-3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
- HEAD
-4. git checkout master
-
-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
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:17:09 +0100
* New upstream release (closes: #500273, #505266).
* Upstream added bash completion (closes: #499072).
- * Provide a TopGit Makefile snippet for inclusion from debian/rules and
- update the README.source workflow accordingly. See
- /usr/share/doc/topgit/README.source for details; thanks to Stefano
- Zacchiroli for the idea (closes: #501991).
+ * Provide the tg2quilt Makefile snippet for inclusion from debian/rules to
+ facilitate generation of the quilt series from TopGit branches. See
+ /usr/share/doc/topgit/HOWTO-tg2quilt for details; thanks to Stefano
+ Zacchiroli for the idea that led to this (closes: #501991).
+ * Update the README.source workflow to refer to HOWTO-tg2quilt.
-- martin f. krafft <madduck@debian.org> Fri, 26 Sep 2008 19:55:58 +0200
README
debian/README.source
+debian/HOWTO-tg2quilt
~ian / topgit.git / commitdiff