[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, master, updated. debian/0.1-4-g9dfee4d
Stephane Glondu
steph at glondu.net
Thu Jan 8 17:49:30 UTC 2009
The following commit has been merged in the master branch:
commit 9dfee4d577d5fb758482a81a0b5df8b6a6313230
Author: Stephane Glondu <steph at glondu.net>
Date: Thu Jan 8 18:23:59 2009 +0100
Add a preliminary documentation for Git
diff --git a/policy/appendix-git.xml b/policy/appendix-git.xml
new file mode 100644
index 0000000..a517678
--- /dev/null
+++ b/policy/appendix-git.xml
@@ -0,0 +1,253 @@
+<section>
+ <title>Using Git for packaging</title>
+ <para>
+ This appendix is still under construction!
+ </para>
+ <para>
+ (Hopefully) All OCaml-related Debian packages are maintained using
+ centralized <ulink url="http://git-scm.com/">Git</ulink>
+ repositories. This practice reduce the efforts needed to contribute
+ work inside &ocaml-force; and, in case of need, provides a place
+ where to massively perform changes to all OCaml-related Debian
+ packages.
+ </para>
+ <para>
+ In the past, we were using Subversion, but we are progressively
+ migrating our packages to Git.
+ </para>
+ <para>
+ Debian users can benefit knowing we are using a Git repository
+ (they can for instance subscribe to the RSS feed for changes or
+ have a place where to look for finding patches corresponding to
+ bugs tagged "pending" in the BTS).
+ </para>
+ <para>
+ For this reason <emphasis>it is recommended to add the
+ <code>Vcs-Git</code> and <code>Vcs-Browser</code> fields to the
+ <filename>debian/control</filename> of packages maintained in
+ &ocaml-force; Git repository</emphasis>. Its name specifies that
+ we are using Git as our Version Control System
+ (<acronym>VCS</acronym>); their values are the URLs pointing to
+ the package's repository and to a browsable view of the same
+ directory. See the
+ <ulink url="http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs">Debian
+ Developer's Reference</ulink> for more information about these
+ fields.
+ </para>
+ <para>
+ The general scheme for using the fields are thus:
+<programlisting> Vcs-Git: git://git.debian.org/git/pkg-ocaml-maint/packages/<emphasis>PACKAGE_NAME</emphasis>.git
+ Vcs-Browser: http://git.debian.org/?p=pkg-ocaml-maint/packages/<emphasis>PACKAGE_NAME</emphasis>.git
+</programlisting>
+ <example>
+ <title>Usage example of the Vcs-* fields, from the
+ <application>findlib</application> package
+ </title>
+<programlisting> Source: findlib
+ Section: devel
+ Priority: optional
+ Maintainer: Debian OCaml Maintainers <debian-ocaml-maint at lists.debian.org>
+ Uploaders: Stefano Zacchiroli <zack at debian.org>
+ Build-Depends: debhelper (>> 5.0.0), ocaml (>= 3.11.0), camlp4 (>= 3.11.0), m4, gawk | awk, dpatch, cdbs, dh-ocaml
+ Standards-Version: 3.8.0
+ <emphasis>Vcs-Git: git://git.debian.org/git/pkg-ocaml-maint/packages/findlib.git</emphasis>
+ <emphasis>Vcs-Browser: http://git.debian.org/?p=pkg-ocaml-maint/packages/findlib.git</emphasis>
+ Homepage: http://projects.camlcity.org/projects/findlib.html
+
+ Package: ocaml-findlib
+ Section: devel
+ Architecture: any
+ Depends: ocaml-nox-${F:OCamlABI}, ${shlibs:Depends}, ${misc:Depends}
+ Description: Management tool for OCaml programming language libraries
+ ...
+</programlisting>
+ </example>
+ </para>
+ <para>
+ This document assumes that you have the following packages
+ installed: <filename>git-buildpackage</filename>
+ and <filename>pristine-tar</filename>.
+ </para>
+</section>
+
+<section>
+ <title>How to obtain a copy of a package's Git repository</title>
+ <para>
+ There is one Git repository per package. To get the list of packages managed with git, you
+ can use the following command (your ssh must be configured properly):
+<programlisting> ssh git.debian.org ls /git/pkg-ocaml-maint/packages
+</programlisting>
+
+ You can obtain a copy of the repository for a package with:
+<programlisting> checkout-d-o-m-git-repo package
+</programlisting>
+ The <application>checkout-d-o-m-git-repos</application> script is
+ available in the Subversion repository. You can get a copy with:
+<programlisting> svn co svn://svn.debian.org/svn/pkg-ocaml-maint/trunk/projects/git-guide
+</programlisting>
+ You must be member of the
+ <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">Debian
+ OCaml Task Force</ulink> in order to have the right to push to the central repository.
+ </para>
+</section>
+
+<section>
+ <title>Structure of a Git repository</title>
+ <para>
+ We keep all upstream sources under Git control, in a branch
+ called <emphasis>upstream</emphasis>. This branch usually
+ consists of successive unpacked upstream tarballs. When
+ importing a new upstream tarball, the following command should
+ be used:
+<programlisting> git-import-orig --pristine-tar [--no-dch] <name_version.orig.tar.gz>
+</programlisting>
+ The <filename>--pristine-tar</filename> is mandatory to store
+ information for reconstructing the upstream tarball from the
+ repository. That information is not suited for human use and
+ is stored in the <emphasis>pristine-tar</emphasis>
+ branch. Optionally, <filename>--no-dch</filename> can be given
+ to automatically update the Debian changelog (without
+ committing it).
+ </para>
+ <para>
+ The <emphasis>master</emphasis> branch contains upstream sources
+ along with the <filename>debian/</filename>
+ directory. <filename>git-import-orig</filename> automatically
+ creates a (local) tag in the upstream branch, and
+ merges <emphasis>upstream</emphasis>
+ into <emphasis>master</emphasis> when importing a new
+ tarball. Changes related to Debian should be done in this
+ branch.
+ </para>
+</section>
+
+<section>
+ <title>How to add a new package</title>
+ <para>
+ Let's take <application>dose2</application> as an example. The
+ following command (the <application>new-d-o-m-git-repo</application> is available at the same location of <application>checkout-d-o-m-git-repo</application>):
+<programlisting> new-d-o-m-git-repo dose2 /some/where/dose2-1.2.tar.gz
+</programlisting>
+ will create the remote repository on Alioth, set up
+ notifications, and inject the given tarball in the repository
+ in the <emphasis>upstream</emphasis> branch
+ (using <filename>pristine-tar</filename>). More
+ details <ulink url="http://wiki.debian.org/Alioth/Git">there</ulink>. You
+ can then check it out and start using it.
+ </para>
+ <para>
+ If the tarball name is
+ missing, <application>new-d-o-m-git-repo</application> will
+ check that the current directory is a git repository, and then
+ push it to Alioth. This allows you to create the repository
+ locally, work on it, and only push it when it is in good
+ shape. It is recommended to check it out after, and use the
+ checked out version, to make sure everything went well, and to
+ have local branches tracking remote ones.
+ </para>
+</section>
+
+<section>
+ <title>How to set up your package for use with <application>git-buildpackage</application></title>
+
+ <para>
+ Put the following in <filename>debian/gbp.conf</filename>:
+<programlisting> # Configuration file for git-buildpackage and friends
+
+ [DEFAULT]
+ # the default branch for upstream sources:
+ upstream-branch = upstream
+ # the default branch for the debian patch:
+ debian-branch = master
+ # use pristine-tar:
+ pristine-tar = True
+</programlisting>
+ The first two settings are not really useful since they are
+ the defaults, but it might be handy to have them around when
+ working with several
+ branches. The <filename>pristine-tar</filename> is necessary
+ if tarballs are imported. Please see
+ the <application>git-buildpackage</application> documentation
+ for complete information.
+ </para>
+
+ <para>
+ If you tried <application>git-buildpackage</application>
+ before writing your <filename>debian/gbp.conf</filename>,
+ remember to delete the <filename>.orig</filename> tarball, and
+ rebuild <emphasis>after</emphasis>
+ writing <filename>debian/gbp.conf</filename>. Alternatively,
+ you can invoke <application>git-buildpackage</application>
+ with the <filename>--git-pristine-tar</filename> option.
+ </para>
+</section>
+
+<section>
+ <title>How to build a package with <application>git-buildpackage</application></title>
+
+ <para>
+ Please refer to the <application>git-builpackage</application>
+ documentation for more complete information. Here is just a
+ quick guide.
+ </para>
+
+ <para>
+ All options, except those starting on <option>--git</option>, are passed to
+ <application>dpkg-buildpackage</application>. Hence, basic
+ usage should be something like this (from the root of the
+ repository): <command>git-buildpackage -rfakeroot -uc
+ -us</command>. The package will be built in place, and the
+ result will be put in the parent directory.
+ </para>
+
+ <para>
+ <application>git-buildpackage</application> will complain when
+ your repository is not clean. You may use the
+ option <option>--git-ignore-new</option> to override this
+ behaviour.
+ </para>
+
+ <para>
+ If your package is ready for upload you may use
+ the <option>--git-tag</option> option for the final
+ build. This will create a tag in your local repository.
+ Provided you have commited all your changes to the Git
+ repository, this will after a successful build of the package
+ create a tag for the current version.
+ </para>
+
+ <tip>
+ <para>
+ Tags created by <application>git-import-orig</application>
+ and <application>git-buildpackage</application> are not
+ automatically pushed, you have to push them explicitly with
+ the following command: <command>git push
+ --tags</command>. Be careful if you use local tags!
+ </para>
+ <para>
+ You can add the <command>--dry-run</command> option
+ to <command>git push</command> to see what will be done.
+ </para>
+ <para>
+ To build with <application>pbuilder</application>
+ (or <application>cowbuilder</application>), use the
+ following:
+<programlisting> git-buildpackage \
+ --git-builder="pdebuild --debbuildopts '-I.git -i\.git -uc -us'" \
+ --git-cleaner="fakeroot debian/rules clean"
+</programlisting>
+ </para>
+ </tip>
+</section>
+
+<section>
+ <title>Patches</title>
+ <para>
+ We have not yet decided on how to deal with patches in upstream
+ (this topic is under discussion). Possibilities include direct
+ commits in the <emphasis>master</emphasis> branch, use
+ of <ulink url="http://repo.or.cz/w/topgit.git">TopGit</ulink>
+ and quilt-serialized patches, and raw quilt or dpatch.
+ </para>
+</section>
+
diff --git a/policy/ocaml_packaging_policy.xml b/policy/ocaml_packaging_policy.xml
index cd5b5f4..7ac4d24 100644
--- a/policy/ocaml_packaging_policy.xml
+++ b/policy/ocaml_packaging_policy.xml
@@ -31,6 +31,7 @@
<!ENTITY appendix-cdbs SYSTEM "appendix-cdbs.xml">
<!ENTITY appendix-resources SYSTEM "appendix-resources.xml">
<!ENTITY appendix-svn SYSTEM "appendix-svn.xml">
+<!ENTITY appendix-git SYSTEM "appendix-git.xml">
]>
<book>
<bookinfo>
@@ -69,4 +70,9 @@
<title>Using the SVN repository</title>
&appendix-svn;
</appendix>
+
+ <appendix>
+ <title>Using Git for packaging</title>
+ &appendix-git;
+ </appendix>
</book>
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list