From c189d21bcab6bd4175cfdd7a1d58bb70c15da67e Mon Sep 17 00:00:00 2001 From: "martin f. krafft" Date: Wed, 19 Nov 2008 15:23:09 +0100 Subject: [PATCH] factor out standard tg2quilt stuff to its own doc Signed-off-by: martin f. krafft --- debian/HOWTO-tg2quilt | 147 ++++++++++++++++++++++++++++++++++++++++++ debian/README.source | 130 ++----------------------------------- debian/changelog | 9 +-- debian/topgit.docs | 1 + 4 files changed, 158 insertions(+), 129 deletions(-) create mode 100644 debian/HOWTO-tg2quilt diff --git a/debian/HOWTO-tg2quilt b/debian/HOWTO-tg2quilt new file mode 100644 index 0000000..3defa51 --- /dev/null +++ b/debian/HOWTO-tg2quilt @@ -0,0 +1,147 @@ +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 + +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 + +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 Wed, 19 Nov 2008 15:16:03 +0100 diff --git a/debian/README.source b/debian/README.source index 7ae068f..dee9b29 100644 --- a/debian/README.source +++ b/debian/README.source @@ -5,130 +5,10 @@ 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.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 Mon, 11 Aug 2008 17:32:48 -0300 + -- martin f. krafft Wed, 19 Nov 2008 15:17:09 +0100 diff --git a/debian/changelog b/debian/changelog index 435b096..97ae1ec 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,10 +2,11 @@ topgit (0.5-1) unstable; urgency=low * 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 Fri, 26 Sep 2008 19:55:58 +0200 diff --git a/debian/topgit.docs b/debian/topgit.docs index 0da37bf..b0126b6 100644 --- a/debian/topgit.docs +++ b/debian/topgit.docs @@ -1,2 +1,3 @@ README debian/README.source +debian/HOWTO-tg2quilt -- 2.30.2