1 files changed, 126 insertions, 0 deletions
diff --git a/debian/README.packaging b/debian/README.packaging
new file mode 100644
index 0000000..c0b03a2
--- /dev/null
+++ b/debian/README.packaging
@@ -0,0 +1,126 @@
+Packaging hints
+===============
+
+This packaging is maintained with the use of Git, using the following
+branches:
+
+    upstream-git  - master branch of upstream Git source
+    upstream      - unpackaged upstream tarballs
+    pristine-tar  - binary deltas to recreate pristine tarballs
+    master        - Debian packaging
+
+With the above, we can switch between working from upstream released
+tarballs and syncing directly with upstream development, both using
+git-buildpackage (with its default branch names).
+
+
+Package sugar-base as example
+-----------------------------
+
+The rest of this document uses sugar-base as sample package, and some
+old actual version numbers from that package - replace with your actual
+package as needed...
+
+
+Getting packaging source from Git repository
+--------------------------------------------
+
+The following commands (in an empty dir) fetch and build the package:
+
+aptitude install git-buildpackage
+git clone git://git.debian.org/git/collab-maint/sugar-base
+cd sugar-base
+git fetch origin upstream:upstream
+git-buildpackage
+
+
+Merging with newer upstream Git tree
+------------------------------------
+
+The following commands (inside Git repository) updates the local mirror
+of upstream source, and merges with our packaging branch:
+
+cd sugar-base
+git checkout upstream-git
+git pull
+git fetch --tags
+git checkout master
+git pull . upstream-git
+
+The following command shows upstream changes possibly relevant to
+mention in changelog (replace "HEAD^" with a reference to actual sync
+commit if not invoked right after sync'ing):
+
+git log --pretty="format:%h %s" HEAD^..upstream-git
+
+
+Doing a package release from upstream tarball
+---------------------------------------------
+
+The following command (inside Git repository) imports a downloaded
+tarball into the "upstream" and pristine-tarball Git branches (taball
+name is recorded too and used later, so make sure to first rename the
+tarball to follow Debian naming convention {name}_{version}.orig.{ext}):
+
+git-import-orig --pristine-tar --sign-tags path/to/sugar-base_0.79.0.orig.tar.gz
+
+Check that all files are included in "upstream" branch (don't know why
+this fails sometimes):
+
+git status
+
+If some files are "untracked", then do the following to manually add
+untracked files to upstream branch and merge them with master branch
+(the stash commands puts changelog update aside and restore it again
+afterwards):
+
+git stash
+git checkout upstream
+git add *
+git commit -m "Add files mysteriously skipped by git-import-orig."
+git checkout master
+git pull . upstream
+git stash apply
+
+Comment out tarball hash in debian/control, test get-orig-source, and
+enable hash line with new hash:
+
+fakeroot debian/rules get-orig-source
+
+Adjust changelog and package, and if satisfied with the result then tag
+it, push Git sources and release the package:
+
+git-buildpackage --git-tag --git-sign-tags
+[test package...]
+git push --all
+git push --tags
+cd ..
+dput sugar-base_0.79.0-1_amd64.changes
+
+
+Doing a package release from upstream Git snapshot
+--------------------------------------------------
+
+First, look at upstream development for a good place to release, and tag
+by its date, replacing "~" with ".".  Normally just tag the latest
+upstream commit, to avoid simply including later upstream work in the
+debian diff:
+
+git log --abbrev-commit upstream-git
+git tag -s -m "Tag upstream for package release." upstream/0.2.git20080130 61279f8
+
+Adjust changelog and package, and if satisfied with the result then tag
+it, push Git sources and release the package:
+
+dch -r -v "0.2~git20080130-0~0jones1" "New upstream Git snapshot."
+debcommit -r -a
+git-buildpackage
+[test package...]
+git tag -s -m "Tag package release." debian/0.2.git20080130-0.0jones1
+git push --all
+git push --tags
+cd ..
+dput sugar-base_0.2~git20080130-0~0jones1_amd64.changes
+
+
+ -- Jonas Smedegaard <dr@jones.dk>  Sat, 08 Mar 2008 01:08:36 +0100