[SCM] Debian Science Policy Manual branch, master, updated. 1c2b6552f39e789c5b06adb76d24b78ab525f047

[Manuel Prinz]

The following commit has been merged in the master branch:
commit 1c2b6552f39e789c5b06adb76d24b78ab525f047
Author: Manuel Prinz <debian at pinguinkiste.de>
Date:   Sun Jun 22 19:43:04 2008 +0200

    Started writing "Help On Packaging" appendix

diff --git a/debian-science-policy.xml b/debian-science-policy.xml
index ba36b69..2db02ec 100644
--- a/debian-science-policy.xml
+++ b/debian-science-policy.xml
@@ -244,12 +244,104 @@ $ chmod 755 hooks/post-receive
   <title>Help on Packaging</title>
   <para>The following sections are not part of the &DebSci; Policy Manual. They should provide useful information for contributors who are not familiar with the tools mentioned in this document.</para>
   <sect1>
-    <title>Patch Systems</title>
-    <para>FIXME</para>
-  </sect1>
-  <sect1>
     <title>Packaging with Git</title>
-    <para>FIXME</para>
+    <para>This section will give you guide on packaging Debian packages with Git. Since Git is a very flexible tool, you can (and should!) adopt it to fit your work-flow best. "There is more than one way to do it", as the saying goes, so this document can not show all of them. It's supposed to help you if you are unfamiliar with using Git for packaging work. It is, however, not supposed to be a normative document that everyone has to follow.</para>
+    
+    <sect2>
+      <title>Creating a Repository</title>
+      <para>Git repositories are nothing more than a directory with a special directory storing meta-data, named <filename>.git/</filename>. Creating and configuring the repository is pretty straight-forward:</para>
+      <screen><![CDATA[
+$ mkdir foo && cd foo
+$ git init
+Initialized empty Git repository in .git/
+$ git config user.name "John Doe"
+$ git config user.email "john at example.org"
+]]></screen>
+      <para>This creates a new Git directory and sets the user name and email address that will be used in the commit message.</para>
+    </sect2>
+    <sect2>
+      <title>Importing Upstream Sources</title>
+      <para>It is quite common for packaging with Git that the upstream sources are stored in the repository. It is, however, not strictly necessary. But the costs are rather low and the benefit can be high, so this section will explain ways to import the upstream sources into you repository.</para>
+      <sect3>
+	<title>Using git-buildpackage and pristine-tar</title>
+	<para>There are two tools that will assist you in packaging with Git a lot: git-buildpackage and pristine-tar.</para>
+	<para>git-buildpackage can import upstream sources, create or import <filename>.diff.gz</filename>s and build a Debian package from Git repositories. It is similar in function to svn-buildpackage or other VCS-buildpackage tools.</para>
+	<para>pristine-tar is able to recreate bit-identical upstream tar-balls from the files stored under version control. It does so by creating small delta files, so that it is not necessary to store the whole tar-ball.</para>
+	<para>To import an upstream tar-ball into your repository, simply run:</para>
+	<screen><![CDATA[
+$ git import-orig --pristine-tar ~/foo_1.0.orig.tar.gz
+Upstream version is 1.0
+Initial import of '/home/jdoe/foo_1.0.orig.tar.gz' ...
+pristine-tar: committed foo_1.0.orig.tar.gz.delta to branch pristine-tar
+Succesfully merged version 1.0 of /home/jdoe/foo_1.0.orig.tar.gz into .
+]]></screen>
+	<para>After that, you will see two new branches, "upstream" and "pristine-tar":</para>
+	<screen><![CDATA[
+$ git branch
+* master
+  pristine-tar
+  upstream
+]]></screen>
+	<para>The upstream branch holds your upstream sources as extracted from the tar-ball. The pristine-tar branch holds the delta files the pristine-tar created. Also, a tag has been created:</para>
+	<screen><![CDATA[
+$ git tag -l
+upstream/1.0
+]]></screen>
+	<para>You can use git-import-orig for every new upstream tar-ball. It will extract the sources to the upstream branch and merge them back to the master branch.</para>
+      </sect3>
+      <sect3>
+	<title>Importing Upstream VCS Data</title>
+	<para>FIXME</para>
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Changes To The Upstream Sources</title>
+      <para>There are at least two methods for doing changes to upstream sources. One uses an integration branch, the other one uses a patch system. Both methods have it's benefits and drawbacks, so you have to decide which methods is best for your purpose.</para>
+      <sect3>
+	<title>Using An Integration Branch</title>
+	<para>By using this model, all changes to the upstream sources are made in independent branches and merged back into a special branch, the "integration" branch. This section tries to explain how this works.</para>
+	<para>When doing changes to the upstream sources, all logical changes should be stored in their own branch, a so-called "feature branch". The hardest part is giving it a reasonable name. If you want to fix a bug submitted to the BTS, you might want to call your branch "bug-nnn", where "nnn" is the bug number. You can also prefix Debian-specific changes with "deb/" to separate them from branches that contain patches which might be included upstream.</para>
+	<note><para>You can also store each patch as one commit in a single feature branch, such as "upstream-patches". It is all up to you. Figure out what work-flow you like best.</para></note>
+	<para>After you thought of a name, you should branch from the latest upstream version. If you used git-import-orig, you can use the tags created by it:</para>
+	<screen><![CDATA[
+$ git checkout -b bug-123456 upstream/1.0
+]]></screen>
+	<para>You can now start fixing the bug inside this branch and commit the changes. For every change to the upstream sources, create a new branch and do your fixes in that until you're done. In the last step, it is time to merge the changes back to the integration branch.</para>
+	<para>FIXME: long-living or temporary integration branch? separate integration branch or master?</para>
+      </sect3>
+      <sect3>
+	<title>Using A Patch System</title>
+	<para>FIXME</para>
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Publishing Your Repository</title>
+      <para>This section will explain how to publish a repository in the &DebSci; scope but should be easy to adopt for other teams or locations.</para>
+      <para>First, login to &Alioth; and create a new shared bare repository:</para>
+      <screen><![CDATA[
+$ cd /git/debian-science/packages/
+$ mkdir foo.git && cd foo.git
+$ git --bare init
+]]></screen>
+      <para>You should also active the post-update-hook to allow checkouts via HTTP.</para>
+      <screen><![CDATA[
+$ chmod a+x hooks/post-update
+]]></screen>
+      <note><para>It is not recommended to use Git over HTTP but it may be handy for people behind a firewall.</para></note>
+      <para>You should also create a hook to send out commit emails to the commits mailing list. FIXME reference</para>
+      <para>The next step only applies if you do not use the "master" branch for storing you debian work. In this case, the HEAD reference in the repository has to be set to point to the branch you are going to push to the repository, or cloning will fail. Assuming your Debian-specific changes are stored in a branch called "debian", do:</para>
+      <screen><![CDATA[
+$ echo 'ref: refs/heads/debian' > HEAD
+]]></screen>
+      <para>The last steps need to be done on your <emphasis>local</emphasis> repository:</para>
+      <screen><![CDATA[
+$ git remote add alioth ssh://user@git.debian.org/git/debian-science/packages/foo.git
+git push --all alioth
+git push --tags alioth
+]]></screen>
+      <para>This tells you local repository about your remote repository and exports all of your branches and tags.</para>
+      <para>All these steps only need to be done once. After that, pushing your changes to the remote repository is all you need to do to publish them.</para>
+    </sect2>
   </sect1>
 </appendix>
 </book>

-- 
Debian Science Policy Manual