038bf35dca649b66cc11476cbb6d3c2f05fadbd5
[collab-maint/racket.git] / 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