From: Guido Günther <agx@sigxcpu.org>
Date: Thu, 22 Aug 2013 08:47:15 +0000 (+0200)
Subject: docs: Add recommended branch layout
X-Git-Tag: debian/0.6.3~6
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=388cfb8fa9912f63168e6150a940e3a0f4cd71ed;p=tools%2Fgit-buildpackage.git

docs: Add recommended branch layout

It'd be nice to have similar branch layouts among packages so recommend
one that worked well so far.
---

diff --git a/docs/chapters/import.sgml b/docs/chapters/import.sgml
index ddb38715..231e36c3 100644
--- a/docs/chapters/import.sgml
+++ b/docs/chapters/import.sgml
@@ -232,6 +232,76 @@ upstream-tag = v%(version)s
       </sect2>
 
     </sect1>
+    <sect1 id="gbp.branch.naming">
+      <title>Branch layout</title>
+      <para>
+	By default &gbp; uses one branch to keep the Debian packaging called <emphasis>master</emphasis>
+	and a branch to keep the upstream packaging called <emphasis>upstream</emphasis>.
+      </para>
+      <para>
+	This layout is simple to get started but fails short if one needs to maintain several versions of
+	the package at the same time. Therefore the following layout is recommended:
+      </para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>
+	    debian/&lt;release&gt;
+	  </term>
+	  <listitem>
+	    <para>
+	      the Debian packaging for a release <emphasis>jessie</emphasis>,
+	      <emphasis>wheezy</emphasis> or <emphasis>sid</emphasis>, <emphasis>experimental</emphasis>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    upstream/&lt;release&gt;
+	  </term>
+	  <listitem>
+	    <para>
+	      the upstream sources for a release matching one of the above
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    security/&lt;release&gt;
+	  </term>
+	  <listitem>
+	    <para>
+	      security updates for a certain release
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    backports/&lt;release&gt;
+	  </term>
+	  <listitem>
+	    <para>
+	      security updates for a certain release
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    dfsg/&lt;release&gt;
+	  </term>
+	  <listitem>
+	    <para>
+	      the dfsg clean upstream sources in case the cleanup is done via a &git;
+	      merge from upstream to this branch.
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+      <para>
+	In case &pristine-tar; is being used there will be a single <emphasis>pristine-tar</emphasis>
+	branch that keeps all binary deltas.
+      </para>
+    </sect1>
 </chapter>
 
 <!--  LocalWords:  tarballs