debian/README.source

   1 This package should be ready to build when the source package is
   2 unpackaged via "dpkg-source -x".
   3
   4 The Debian packaging for racket (previously known as plt-scheme) is now stored in git.
   5
   6 * Branch Layout
   7
   8   Currently there are three main branches
   9
  10  - dfsg contains the release branch history, along with file deletions
  11    to make it match the upstream release tar balls, and some further
  12    deletions of non-free bits. Tags are upstream/$ver where $ver is an
  13    upstream version.
  14
  15  - patch-queue/dfsg contains patches on top of dfsg. Tags are
  16    patches/$debian_ver where $debian_ver is a debian version. This
  17    branch is rebased for each new upstream version.
  18
  19  - master is merged debian packaging and upstream commits.
  20
  21    Tags are debian/$debian_ver where $debian_ver is a debian version.
  22    To get a list of packaging commits, run
  23
  24       git log dfsg..
  25
  26 There is also a branch pristine-tar contains information used by the
  27 pristine-tar utility to reconstruct bit identical upstream tarball.
  28 There was a branch debian of just packaging commits, but I (David)
  29 kept forgetting to use it.
  30
  31 The master branch is a debianized source tree, and should be buildable
  32 by any number of tools (including dpkg-buildpackage).
  33
  34 * gitpkg and sbuild basics
  35
  36   My (David's) preferred workflow is based on gitpkg and sbuild.  To
  37   tell gitpkg to use the tarballs from git,
  38
  39   % git config gitpkg.pre-export-hook /usr/share/gitpkg/hooks/pristine-tar-pre-export-hook
  40
  41 ** Make a source package. This relies on gitpkg (>= 0.19)
  42
  43   % gitpkg master
  44
  45 ** Build existing debian version
  46    - gitpkg debian/$version
  47
  48 ** Problems with pristine-tar?
  49    pristine-tar Needs a large TMPDIR.  I found even 180M free in /tmp
  50    is not enough. Try
  51
  52      export TMPDIR=/var/tmp
  53
  54 * New upstream version
  55
  56 ** Update upstream branch
  57    - git checkout upstream
  58    - git merge -s recursive -X theirs vXXXX
  59      # where vXXXX is an upstream tag. Since v5.0.1, these tags should all be on
  60      # upstream branch stable.
  61
  62    - optionally auto resolve file deletion conflicts:
  63      - git status -s | egrep '^(DU|UA| U|U |UD)' | cut -c4- | xargs git rm --ignore-unmatch DUMMY$$
  64      - git commit
  65
  66 ** Import upstream tarball
  67
  68    We do a manual import, because e.g. git-import-orig wants to merge
  69    into master. I have a git alias [1] which does most of this
  70
  71      - git checkout upstream
  72      - git clean -fxd
  73      - git ls-files -z | xargs -0 rm -f
  74      - tar --strip-components=1 -zxf $tarball
  75      - git add -A
  76      - git commit -m 'Importing '`basename $tarball`
  77      - pristine-tar commit $tarball
  78
  79 ** Update dfsg branch
  80    - git checkout dfsg
  81    - git merge upstream
  82
  83    - probably the same conflicts with deletions exist here, which can
  84      be resolved as above.
  85
  86    - git tag upstream/$version+dfsg1
  87
  88 ** Make a tarball
  89
  90    git checkout master && ./debian/rules get-orig-source
  91    pristine-tar commit ../racket_$version.orig.tar.gz
  92
  93 * Managing patches
  94
  95 Patches are exported based on debian/source/git-patches; each line is
  96 an argument to git-format-patch. The variables $DEB_VERSION and
  97 $UPSTREAM_VERSION are the Debian and upstream version being exported.
  98 You can either use git-format-patch manually, or install gitpkg
  99 version 0.17 or later.
 100
 101 1) To have the patches automatically exported at source package creation time
 102
 103   a) to setup gitpkg, run
 104
 105      % git config gitpkg.deb-export-hook /usr/share/gitpkg/hooks/quilt-patches-deb-export-hook
 106
 107   b) run
 108
 109       % gitpkg master
 110
 111      to make a source package including patches.
 112
 113 2) To manually export patches, run
 114
 115        % ./debian/rules export-patches
 116
 117
 118 Notes:
 119
 120 [1] My git alias to import tarballs is
 121
 122  [alias]
 123         import-tgz = "!f() { if [ -f $1 ]; then git clean -fxd; git ls-files -z | xargs -0 rm -f; tar --strip-components=1 -zxvf $1 ; git add -A; git commit -m'Importing '`basename $1`; else echo "missing tarball $1"; fi; }; f"
 124
 125
 126  -- David Bremner <bremner@debian.org>, Fri, 27 May 2011 18:37:25 -0300
 127