summaryrefslogtreecommitdiff
path: root/docs/chapters/intro.sgml
blob: ecdeb3fa80cf4aa687ea569f371a57de4fcf9a3f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
<chapter id="gbp.intro">
    <title>Introduction</title>
    <para>
      Welcome to &gbp;, a system that integrates the
      <ulink url="http://www.debian.org/">Debian</ulink> package build
      system with <ulink url="http://git.or.cz/">Git</ulink>. The current version of this manual can be found at
      <ulink url="https://honk.sigxcpu.org/piki/projects/git-buildpackage">here</ulink>.
    </para>
    <para>
    What can these tools do for you:
    <itemizedlist>
    <listitem><para>Import an existing &debian; package into &git;</para></listitem>
    <listitem><para>Import new upstream versions, NMUs etc. with optional filters</para></listitem>
    <listitem><para>Automatic upstream tarball generation</para></listitem>
    <listitem><para>Maintain a consistent branch and tag naming across
    repositories or across a team of developers</para></listitem>
    <listitem><para>Automatically sign tags</para></listitem>
    <listitem><para>Automatically push changes to remote repositories</para></listitem>
    <listitem><para>Make sure you have committed all changes to the right
    branch before releasing</para></listitem>
    <listitem><para>Export to a clean build area before building</para></listitem>
    <listitem><para>Automatic debian/changelog generation</para></listitem>
    <listitem><para>Automatic generation of snapshot releases for local testing</para></listitem>
    <listitem><para>Simple patch management</para></listitem>
    </itemizedlist>
    All of this is (hopefully) being done without restricting the user to certain usage patterns.
    </para>

<sect1 id="gbp.repository">
	<title>Repository Layout and Terminology</title>
	<para>The only requirement on the repository layout for using
	&gbp; is, that the branch the debian work is
	being done on is different from the branch the upstream sources are
	being maintained on (this, of course, has no meaning for Debian native
	packages). This is necessary to be able to build upstream tarballs and
	to merge in new upstream versions. To distinguish these two branches
	the following terminology <footnote><para>corresponding to the command
	line and config file options</para></footnote> is used:
	</para>
	<itemizedlist>
	<listitem><para>The <option>debian-branch</option> (the default branch
	name used in the &git; repository is <emphasis>master</emphasis>) holds
	your current development work.  That's the branch you usually cut your
	releases from and the default branch new upstream releases are merged
	onto.</para></listitem>

	<listitem><para> The <option>upstream-branch</option> (the default
	branch name used in the &git; repository is
	<emphasis>upstream</emphasis>) holds the upstream releases. This can
	either be a branch you import to or a branch of an upstream repository
	you pull from.</para></listitem>

	<listitem><para> The <option>pristine-tar branch</option> (the default
	branch name used in the &git; repository is
	<emphasis>pristine-tar</emphasis>) holds the necessary additional
	information to recreate the original tarball from the
	<option>upstream-branch</option>. In order to use this feature you need
	to install the &pristine-tar; package.</para></listitem>

	<listitem><para> There can be one or more <option>patch-queue
	branches</option>. Every patch-queue branch is related to a
	<option>debian-branch</option>. If the <option>debian-branch</option> is called
	<emphasis>master</emphasis> the corresponding patch-queue branch is
	called <emphasis>patch-queue/master</emphasis>. The patch-queue branch is 
	the debian branch plus the contents of
	<emphasis>debian/patches</emphasis> applied. These branches are managed
	with &gbp-pq;.
	</para></listitem>
	</itemizedlist>

	<para>You're completely
	free to pick any repository layout and the branch names above are only
	&gbp;'s defaults. They can be changed at any point in time
	and you can work with an arbitrary number of branches.
	For example branches like  <emphasis>nmu</emphasis>,
	<emphasis>backports</emphasis> or <emphasis>stable</emphasis> might
	(temporarily or permanent) become your <option>debian-branch</option>
	and branches like <emphasis>dfsg</emphasis> or
	<emphasis>snapshots</emphasis> might become your
	<option>upstream-branch</option> - it doesn't matter if these branches
	are maintained with &gbp-import-orig; or not.</para>
        <para>
        A recommended branch layout is described in <xref linkend="gbp.branch.naming">.
        </para>

	<para>Since &gbp-buildpackage; only works with local &git;-repositories
	you have to use <command>git push</command> in order to publish your
	changes to remote repositories like <ulink
	url="http://git.debian.org/">git.debian.org</ulink>, this can also be
	automized with &gbp-buildpackage;'s <option>post-tag</option>
	hook.</para>
</sect1>

<sect1 id="gbp.workflow">
    <title>Workflow</title>
    <para>
    	A typical, simple workflow consists of the following steps:
    </para>
    <orderedlist>
	<listitem><para>Import a new Debian package via &gbp-import-dsc;. This
	imports the &debian; Package on the <option>debian-branch</option>
	and the upstream sources on the <option>upstream-branch</option>.</para></listitem>
	<listitem><para>Develop, test, commit changes. During this time you can
	always build the package with &gbp-buildpackage;. In case you have
	uncommitted changes in your source tree you can use the
	<option>--git-ignore-new</option> option.</para></listitem>
	<listitem><para>Optionally you can create the Debian changelog entries
	using &gbp-dch; and create snapshot releases for testing using its
	<option>--snapshot</option> option.</para></listitem>
	<listitem><para>Once satisfied you can build the final package with
	&gbp-buildpackage; <option>--git-tag</option>. This additionally
	creates a tag within &git; so you can switch back to that version later
	at any time. The format of the tags can be specified, tags can
	be &gpg; signed.</para></listitem>
	<listitem><para>When a new upstream version is released and upstream
	isn't using &git; you can import the new version via &gbp-import-orig;
	onto the <option>upstream-branch</option>.  &gbp-import-orig; will
	by default try to merge the new upstream version onto the
	<option>debian-branch</option>. You can skip the merge with
	<option>--no-merge</option>.  After resolving any potential conflicts
	go back to the second step.  </para></listitem>
    </orderedlist>
    <para>These steps will be explaind in more details in the following sections.</para>
</sect1>

</chapter>