[SCM] website branch, master, updated. 2887b4c30ce0e0b6532bbc220a7fa2c409f4ee18
Bas Couwenberg
sebastic at xs4all.nl
Sun Jan 5 03:32:37 UTC 2014
The following commit has been merged in the master branch:
commit 2887b4c30ce0e0b6532bbc220a7fa2c409f4ee18
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date: Sun Jan 5 04:22:37 2014 +0100
Restructure Packaging section, move SCM tips from Repositories section.
The Repositories section now only documents access to the SCM repos,
their common structures, and tips for migrating from SVN to Git.
The SCM specific tips sections have moved to the Subversion and Git subsections
of the Packaging section.
The Packaging section has gained an initial Packaging with Git subsection,
documenting the tools commonly used, and a skeleton Packaging walkthrough.
The Git tips subsection will be further adapted into the Packaging walkthough.
diff --git a/policy.xml b/policy.xml
index 294baab..6666710 100644
--- a/policy.xml
+++ b/policy.xml
@@ -101,6 +101,13 @@
You may also consider to write respective articles for Magazines, be they
online or in print.
</para>
+ <para>
+ This policy is a work in progress, and attempts to document best
+ practices which evolve and change over time. Different people tend to do
+ things in different ways. If your way diverges, you may want to document
+ it here so that others can benefit. Please send any comments or ideas to
+ <ulink url="mailto:debian-gis at lists.debian.org">debian-gis at lists.debian.org</ulink>.
+ </para>
<sect2 id="membership">
<title>Membership</title>
<para>
@@ -228,8 +235,8 @@ Host *.debian.org
<ulink url="http://wiki.debian.org/Alioth/SSH">this wiki article</ulink>.
</para>
</sect2>
- <sect2 id="git-repository-structures">
- <title>Common Git repository structures</title>
+ <sect2 id="git-repository">
+ <title>Git repository</title>
<para>
The area on Alioth that contains the Git repositories
(<filename class="directory">/git/pkg-grass</filename>)
@@ -290,32 +297,7 @@ pkg-grass/
don't forget to use it when you stop working on the package.
</para>
<sect3 id="git-branches">
- <title>Other branches</title>
- <para>
- Changes uploaded to other distributions than
- <literal>unstable</literal> can be stored in other branches,
- named for instance <literal>experimental</literal>,
- <literal>jessie</literal>, etc.
- </para>
- <para>
- Packaging for the
- <link linkend="ubuntugis-ppa">UbuntuGIS PPA</link> is encouraged to
- be stored in Ubuntu release specific branches such as
- <literal>ubuntu/raring</literal>,
- <literal>ubuntu/quantal</literal>, etc.
- </para>
- <para>
- Likewise packaging for
- <link linkend="derivatives">other derivatives</link>
- can be maintained in the Debian GIS git repository in derivative
- specific branches.
- OSGeo-Live for example can use branches such as
- <literal>osgeo/7.0</literal>,
- <literal>osgeo/8.0</literal>, etc.
- </para>
- </sect3>
- <sect3 id="git-buildpackage">
- <title><command>git-buildpackage</command></title>
+ <title>Common Git branches</title>
<para>
Most of our packages using Git and stored in Alioth are managed
following the standard layout of the
@@ -343,6 +325,31 @@ pkg-grass/
file and not the one committed in the Git repository.
</para>
</sect3>
+ <sect3 id="other-git-branches">
+ <title>Other Git branches</title>
+ <para>
+ Changes uploaded to other distributions than
+ <literal>unstable</literal> can be stored in other branches,
+ named for instance <literal>experimental</literal>,
+ <literal>jessie</literal>, etc.
+ </para>
+ <para>
+ Packaging for the
+ <link linkend="ubuntugis-ppa">UbuntuGIS PPA</link> is encouraged to
+ be stored in Ubuntu release specific branches such as
+ <literal>ubuntu/raring</literal>,
+ <literal>ubuntu/quantal</literal>, etc.
+ </para>
+ <para>
+ Likewise packaging for
+ <link linkend="derivatives">other derivatives</link>
+ can be maintained in the Debian GIS git repository in derivative
+ specific branches.
+ OSGeo-Live for example can use branches such as
+ <literal>osgeo/7.0</literal>,
+ <literal>osgeo/8.0</literal>, etc.
+ </para>
+ </sect3>
<sect3 id="git-without-tarball">
<title>Social Git</title>
<para>
@@ -366,273 +373,8 @@ pkg-grass/
</para>
</sect3>
</sect2>
- <sect2 id="git-tips">
- <title>Git tips</title>
- <sect3 id="git-options-devscripts">
- <title>
- Set the <package>devscripts</package> variables
- <varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname>
- </title>
- <para>
- <command>debcheckout</command> will then set <command>git</command>'s
- options <varname>user.email</varname> and <varname>user.name</varname>
- accordingly.
- </para>
- </sect3>
- <sect3 id="debcheckout-sets-git-options">
- <title>Configure Git to commit using your packager name and address.</title>
- <para>
- The <option>--global</option> option is to say Git these are the
- default parameters for every Git repository you commit to,
- without it the settings will be per-repository only:
- </para>
- <para>
-<programlisting>
-<command>git config</command> <option><optional>--global</optional></option> <option>user.name "$DEBFULLNAME"</option>
-<command>git config</command> <option><optional>--global</optional></option> <option>user.email "$DEBEMAIL"</option>
-</programlisting>
- </para>
- </sect3>
- <sect3 id="new-repository-with-gbp">
- <title>To create a new local git repository</title>
- <para>
- When the upstream sources are distributed as compressed
- <command>tar</command> archives (<literal>tar.gz</literal>, …):
- </para>
- <para>
-<programlisting>
-<command>mkdir</command> <replaceable><package></replaceable>
-<command>cd</command> <replaceable><package></replaceable>
-<command>git init</command>
-<command>git import-orig</command> <option>--pristine-tar</option> <filename><replaceable>/path/to/package_version.orig.tar.gz</replaceable></filename>
-<command>dh_make</command> <option>-p <replaceable>package_x.y.z</replaceable></option>
-</programlisting>
- </para>
- <para>
- The above steps will create a repository with the appropriate layout
- for <command>git-buildpackage</command>, with three branches:
- <itemizedlist>
- <listitem>
- <para>
- <literal>master</literal>,
- where the Debian development will happen,
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pristine-tar</literal>, used by the
- <command>pristine-tar</command> tool during the package build
- process to recreate the original tarball, and
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>upstream</literal>,
- which will contain the upstream source.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
- <sect3 id="debcheckout-git-track">
- <title>To clone and follow every branch of a git repository.</title>
- <para>
- When the package is already in the Debian archive, you can use the
- <command>debcheckout</command> command with its
- <option>--git-track='*'</option> option.
- </para>
- <para>
- To update the <literal>master</literal>, <literal>upstream</literal>
- and <literal>pristine-tar</literal> branches at once, use the
- <command>gbp-pull</command>.
- </para>
- </sect3>
- <sect3 id="git-track-new-branches">
- <title>To track extra upstream branches, simply check them out.</title>
- <para>
- With recent versions of git, the remote branch will be automatically
- tracked when running <command>git</command> checkout.
- </para>
- <para>
- For example, when a <literal>pristine-tar</literal> branch is
- available upstream and not yet tracked locally, the command
- <command>git checkout</command> <option>pristine-tar</option>
- will implicitely run the command
- <command>git branch</command> <option>-t pristine-tar origin/pristine-tar</option>.
- </para>
- </sect3>
- <sect3 id="create-git-repository-on-alioth">
- <title>Pushing to git.debian.org, creating a new bare repository on Alioth.</title>
- <para>
- Before pushing to git.debian.org for the first time,
- an empty repository needs to be created there.
- </para>
- <para>
- To do this connect to <literal>git.debian.org</literal>, enter the
- <filename class="directory">/git/pkg-grass</filename> directory,
- and run the <command>./setup-repository</command> script.
- </para>
- <para id="example-create-bare-git-repository-on-alioth">
- Run it similar to:
-<programlisting>
-<command>ssh</command> git.debian.org
-<command>cd</command> /git/pkg-grass
-<command>./setup-repository</command> <replaceable><package></replaceable> 'Packaging of <replaceable><package></replaceable> in Debian'
-</programlisting>
- </para>
- <para>
- This will create an empty, bare, shared Git repository and setup some
- hooks. Each package is kept in its own Git repository.
- </para>
- <para>
- Now, on your local machine add the Alioth repository as a remote:
- </para>
- <para>
-<programlisting>
-<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://git.debian.org/git/pkg-grass/<package>.git</filename>
-</programlisting>
- </para>
- <para>
- This is done automatically after cloning a repository, for instance
- with <link linkend="debcheckout-git-track">debcheckout</link>.
- The default remote branch is called <quote>origin</quote>.
- </para>
- </sect3>
- <sect3 id="git-change-default-branch">
- <title>To change the default branch.</title>
- <para>
- If the Debian work is not on the <literal>master</literal> branch,
- change the default branch by editing the <filename>HEAD</filename>
- file in the bare repository on Alioth, and replace
- <literal>master</literal> by the name of the new default branch.
- For a branch called <literal>debian/unstable</literal> the contents
- of the file will be <literal>refs/heads/debian/unstable</literal>.
- </para>
- </sect3>
- <sect3 id="push-package-to-alioth">
- <title>To push the package.</title>
- <para>
- (make sure you've added the alioth remote!), do the following:
- <command>git push</command> <option>origin master</option>.
- For the first push, it's necessary to specify
- <option>origin master</option>. The next time you will push, a
- <command>git push</command> will suffice.
- </para>
- <para>
- Or use the <option>--set-upstream</option> option, helps future use of
- <command>git pull</command>.
-<programlisting>
-<command>git</command> push --set-upstream
-</programlisting>
- </para>
- </sect3>
- <sect3 id="git-push-all-tags">
- <title>To push all your work</title>
- <para>
- Be sure to also do a run <command>git push</command> with
- <option>--all</option>, and one with <option>--tags</option>
- if you created new tags.
-<programlisting>
-<command>git</command> push --all --set-upstream
-<command>git</command> push --tags
-</programlisting>
- </para>
- </sect3>
- <sect3 id="git-tag-release">
- <title>To tag a release</title>
- <para>
- <command>git tag</command> <option>debian/x.y-z</option>.
- You can also easily retroactively make tags:
- <command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option>.
- Remember to <command>git push --tags</command>.
- </para>
- </sect3>
- <sect3 id="git-debian-version-from-commit">
- <title>If upstream manages his sources with Git.</title>
- <para>
- The following makefile script can help producing a version number
- when no Git tag is available:
-<programlisting>
-SOURCEPKG=$(shell dpkg-parsechangelog | sed -n 's/^Source: \(.*\)/\1/p')
-UPSTREAM=$(shell dpkg-parsechangelog | sed -n 's/^Version: \(.*\)-[^-]*/\1/p')
-SHA1=$(lastword $(subst ~g, ,$(UPSTREAM)))
-ORIG=${SOURCEPKG}_${UPSTREAM}.orig.tar.gz
-
-describe-current-version:
- git describe --tags upstream | sed 's,^release-,,;s,-,+,;s,-,~,;'
-
-get-orig-source:
- git archive --format=tar $(SHA1) | gzip -9 > ../$(ORIG)
-</programlisting>
- </para>
- </sect3>
- <sect3 id="git-pbuilder">
- <title>
- To make <command>git-buildpackage</command> build the package
- with <command>pdebuild</command>.
- </title>
- <para>
- Add the following to the configuration file
- <filename>~/.gbp.conf</filename> or
- <filename>debian/gbp.conf</filename>:
-<programlisting>
-[DEFAULT]
-builder = ~/bin/git-pbuilder
-</programlisting>
- With this configuration file you're specifying that
- <command>git-buildpackage</command> will use
- <filename>~/bin/git-pbuilder</filename> as the builder script.
- This is an example script you can use:
-<programlisting>
-#!/bin/sh
-set -e
-
-pdebuild --pbuilder cowbuilder --debbuildopts "-i\.git -I.git $*"
-rm ../*_source.changes
-</programlisting>
- This will build the package inside the default cowbuilder chroot,
- while passing any more parameters directly do
- <command>dpkg-buildpackage</command>.
- </para>
- </sect3>
- </sect2>
- <sect2 id="updating-git-package">
- <title>Updating a source package managed with Git</title>
- <para>
- Most source packages maintained as Git repositories in Debian GIS
- are using the <command>git-buildpackage</command> helper toolkit.
- In doubt, try this one first.
- </para>
- <para>
- <command>git-buildpackage</command>'s command
- <command>git-import-orig</command> makes it easy to update of the
- <emphasis>upstream</emphasis> branch using upstream releases
- distributed as a compressed archive, and to merge these changes in
- the <emphasis>master</emphasis> branch. Its option
- <command>--pristine-tar</command> is useful for stabilizing the MD5 sum
- of the "<filename>orig.tar.gz</filename>" produced when building a
- source package from the repository alone (not doing so results in
- archive rejection of package updates). With recent versions of
- <command>git-buildpackage</command>, it is often unnecessary to rename
- the freshly downloaded original upstream archive.
- </para>
- <para>
- If you do not use <command>git-buildpackage</command>, please use
- <command>pristine-tar</command> anyway to register the compressed
- archives that you upload to Debian as original upstream sources
- (the <literal>orig.tar.{gz|bz2|xz}</literal> file), with a command
- such as the following, where <replaceable><tarball></replaceable>
- is a path to the archive file and
- <replaceable><tag></replaceable> is the upstream release tag
- for that archive (as a fallback, if you created the tarball from a
- given branch, use the name of the branch).
-<programlisting>
-<command>pristine-tar commit</command> <option><replaceable><tarball></replaceable></option> <option><replaceable><tag></replaceable></option>
-</programlisting>
- </para>
- </sect2>
- <sect2 id="svn-repository-structure">
- <title>Subversion repository structure</title>
+ <sect2 id="svn-repository">
+ <title>Subversion repository</title>
<para>
The SVN repository is structured as follows:
<programlisting>
@@ -656,100 +398,6 @@ pkg-grass/
</programlisting>
</para>
</sect2>
- <sect2 id="subversion-tips">
- <title>Subversion tips</title>
- <para id="svn-buildpackage-aliases">
- Suggested aliases for <command>svn-buildpackage</command>:
-<programlisting>
-alias <command>svn-b</command>='svn-buildpackage -us -uc --svn-ignore'
-alias <command>svn-br</command>='svn-b --svn-dont-purge --svn-reuse'
-alias <command>svn-bt</command>='svn-buildpackage --svn-tag'
-</programlisting>
- </para>
- <para id="svn-mergewithupstream">
- <command>svn-inject <replaceable>-o</replaceable></command> sets up the
- <literal>mergeWithUpstream</literal> property for the SVN directories
- where packages are stored. In case <command>svn-inject</command>
- was not used, you can do it by hand with the command
- <command>svn propset</command>
- <replaceable>mergeWithUpstream</replaceable>
- <replaceable>1</replaceable> <replaceable>debian</replaceable>.
- </para>
- <para id="download-upstream-source">
- To download the upstream sources (if there is a
- <filename>debian/watch</filename> file):
- <command>echo "origDir=.." >> .svn/deb-layout && uscan --force-download</command>.
- Alternatively, you can try
- <command>debian/rules get-orig-source</command>.
- </para>
- <para id="svn-write-access">
- If you're a Debian Developer or a member of the pkg-grass group on
- Alioth, you can commit your changes: <command>svn commit</command>
- (also <command>svn ci</command>). Otherwise, you can ask to be added
- to the group (see the <link linkend="membership">Membership</link>
- section), or send the result of <command>svn diff</command> to the
- <ulink url="mailto:debian-gis at lists.debian.org">mailing list</ulink>
- (<command>gzip -9</command> it, if it's too large).
- </para>
- <para id="svn-tag-release">
- It may happen that a package version has been uploaded to Debian
- repositories, and you forgot to tag the last build with
- <command>svn-buildpackage --svn-tag</command>. You can tag this
- package also retroactively. A first step, creating the tags directory,
- can be achieved in two ways: either create it locally as sibling of
- <filename class="directory">trunk/</filename> with
- <command>svn mkdir</command>
- <filename class="directory">tags</filename>, and commit with
- <command>svn commit</command>, or create it remotely with
- <command>svn mkdir</command>
- <filename class="directory">svn+ssh://<user>@svn.debian.org/svn/pkg-grass/packages/<package>/tags</filename>.
- After the tags directory has been created, you're ready to tag the
- package: <command>svn-buildpackage</command>
- <option>--svn-tag-only</option> <option>--svn-no-autodch</option>.
- The <option>--svn-no-autodch</option> avoids
- <filename>debian/changelog</filename> to be marked as
- <literal>UNRELEASED</literal>.
- </para>
- <para id="example-svn-session">
- Here is an example session where a package is prepared manually:
-<programlisting>
-# Check out pkg-grass, cd to pkg-grass/packages
-# Create new project folder with
-svn mkdir projectname
-svn mkdir projectname/trunk
-
-# Put orig.tar.gz in place
-mv some_version.orig.tar.gz projectname
-
-# Inform svn-buildpackage about the location of the orig.tar.gz
-echo "origDir=.." > projectname/trunk/.svn/deb-layout
-
-# Untar source tree for development
-cd projectname
-tar xzvf some_version.orig.tar.gz
-cd some-version # entering the unpackaged source tree
-if [ ! -d debian ]; then dh_make ; fi
-mv debian ../trunk
-ln -s ../trunk/debian .
-
-# continue development
-fakeroot ./debian/rules binary
-
-# until it works, finally
-cd ..
-
-# debian directory is the only thing that is stored in svn, to be merged with upstream svn propset merge with upstream
-svn propset mergeWithUpstream 1 trunk/debian
-
-# See if things can be compiled via svn-buildpackage
-cd trunk
-svn-buildpackage -uc -us
-
-# check build
-lintian ../build-area/*changes
-</programlisting>
- </para>
- </sect2>
<sect2 id="subversion-to-git">
<title>Migration of a source package from Subversion to Git.</title>
<para>
@@ -820,7 +468,7 @@ lintian ../build-area/*changes
</sect1>
<sect1 id="packaging">
<title>Packaging</title>
- <sect2 id="packagingguidelines">
+ <sect2 id="packaging-guidelines">
<title>Newcomer guidelines for building proper Debian packages</title>
<para>
Some newcomers tend to go the create DEBIAN dir, move files around and
@@ -856,14 +504,614 @@ lintian ../build-area/*changes
<acronym>WNPP</acronym> field name.
</para>
</sect2>
+ <sect2 id="git-packaging">
+ <title>Packaging with Git</title>
+ <para>
+ This section describes the procedures that Debian GIS contributors use
+ to maintain packages in the Git repositories on git.debian.org.
+ </para>
+ <para>
+ It covers how to upload an initial package, how to update packages,
+ how to build them, how to upgrade them, and how to package for
+ derivatives.
+ </para>
+ <para>
+ For a more general guide to Git, see the Git User's Manual at
+ <ulink url="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html">http://www.kernel.org/pub/software/scm/git/docs/user-manual.html</ulink>.
+ </para>
+ <sect3 id="git-tools">
+ <title>Tools</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>git-buildpackage</command> and its helper tools
+ are used by most source packages maintained as Git repositories
+ in Debian GIS.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>pristine-tar</command> is used to allow byte-identical
+ recreation of the original tarball from the
+ <literal>upstream</literal> branch.
+ </para>
+ <para>
+ Use <command>git-buildpackage</command>'s
+ <option>--git-pristine-tar</option> option to generate missing
+ upstream tarballs with the <command>pristine-tar</command>
+ command from the <literal>upstream</literal> and
+ <literal>pristine-tar</literal> branches in the Git repository.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>pbuilder</command> and <command>cowbuilder</command> are
+ used for clean builds from the source packages in distribution
+ specific <literal>chroot</literal> environments.
+ </para>
+ <para>
+ Use <command>git-buildpackage</command>'s
+ <option>--git-pbuilder</option> option to use
+ <command>cowbuilder</command> for building the package in a clean
+ <literal>chroot</literal> instead of on the development system
+ itself using plain <command>debuild</command>.
+ </para>
+ <para>
+ <command>cowbuilder</command> is preferred for over
+ <command>pbuilder</command> by
+ <command>git-buildpackage</command> for its increased
+ performance using Copy-On-Write techniques.
+ </para>
+ <para>
+ <command>pbuilder</command> can be selected instead by setting
+ the environment variable <literal>BUILDER</literal> to
+ "<literal>pbuilder</literal>", and
+ <command>qemubuilder</command> can be selected by setting
+ <literal>BUILDER</literal> to "<literal>qemubuilder</literal>".
+ </para>
+ <para>
+ Use <command>git-buildpackage</command>'s
+ <option>--git-dist=<replaceable><distribution></replaceable></option>
+ option for building packages in distribution specific chroots,
+ such as <literal>stable-updates</literal> using the branch
+ named the same as the release codename or version.
+ </para>
+ <para>
+ The default path for <command>cowbuilder</command> chroots is
+ <filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.cow</filename>.
+ And for <command>pbuilder</command> chroots
+ <filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.tgz</filename>.
+ </para>
+ <para>
+ Use <command>cowbuilder</command>
+ <option>--create</option>
+ <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg>
+ <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.cow</filename></arg>
+ to create <command>cowbuilder</command> chroots for specific
+ distributions.
+ </para>
+ <para>
+ Use <command>pbuilder</command>
+ <option>--create</option>
+ <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg>
+ <option>--basetgz=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.tgz</filename></arg>
+ when using <command>pbuilder</command> instead.
+ </para>
+ <para>
+ Use <command>git-buildpackage</command>'s
+ <option>--git-arch=<replaceable><architecture></replaceable></option>
+ option for building packages targetting a different architecture,
+ such as building <literal>i386</literal> packages on
+ <literal>amd64</literal>.
+ </para>
+ <para>
+ The default path for architecture specific
+ <command>cowbuilder</command> chroots is
+ <filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>-<replaceable><architecture></replaceable>.cow</filename>.
+ And for <command>pbuilder</command> chroots
+ <filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>-<replaceable><architecture></replaceable>.tgz</filename>.
+ </para>
+ <para>
+ Use <command>cowbuilder</command>
+ <option>--create</option>
+ <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg>
+ <option>--architecture=</option><arg choice="plain"><replaceable><architecture></replaceable></arg>
+ <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>-<replaceable><architecture></replaceable>.cow</filename></arg>
+ to create <command>cowbuilder</command> distribution and
+ architecture specific chroots.
+ </para>
+ <para>
+ Or <command>cowbuilder</command>
+ <option>--create</option>
+ <option>--architecture=</option><arg choice="plain"><replaceable><architecture></replaceable></arg>
+ <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><architecture></replaceable>.cow</filename></arg>
+ to create <command>cowbuilder</command> chroots for only
+ specific architectures.
+ </para>
+ <para>
+ Replace <option>--basepath</option> with
+ <option>--basetgz</option> for the respective
+ <command>pbuilder</command> commands.
+ </para>
+ <para>
+ Use <command>git-buildpackage</command>'s
+ <option>--git-debian-branch=<replaceable><branch_name></replaceable></option>
+ option when the content of the <filename>debian/</filename>
+ directory for the target distribution is not maintained in the
+ <literal>master</literal> branch.
+ </para>
+ <para>
+ Packages targetting <link linkend="ubuntugis-ppa">UbuntuGIS</link>
+ or derivatives such as
+ <ulink url="http://live.osgeo.org/">OSGeo-Live</ulink> can be
+ built from their distribution specific branches.
+ <itemizedlist>
+ <listitem>
+ <para>
+ UbuntuGIS branches should be named
+ <literal>ubuntu/<codename></literal>,
+ for example <literal>ubuntu/precise</literal>,
+ <literal>ubuntu/quantal</literal>, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ OSGeo-Live branches should be named
+ <literal>osgeo/<version></literal>,
+ for example <literal>osgeo/7.0</literal>,
+ <literal>osgeo/8.0</literal>, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Branches for other derivatives should be named
+ <literal><derivative>/<codename|version></literal>.
+ </para>
+ <para>
+ Using release codenames is preferred over release versions,
+ but the latter are reasonable when codenames are not used.
+ </para>
+ <para>
+ If the packaging workflow benefits more from tracking
+ release aliases such as <literal>stable</literal>,
+ <literal>testing</literal> or <literal>unstable</literal>
+ this is also possible.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ <sect3 id="git-walkthrough">
+ <title>Packaging walkthrough</title>
+ <para>
+
+ </para>
+ <sect4 id="git-new-package">
+ <title>Starting a new package</title>
+ <para>
+
+ </para>
+ </sect4>
+ <sect4 id="git-existing-package">
+ <title>Working with existing packages</title>
+ <para>
+
+ </para>
+ </sect4>
+ <sect4 id="git-new-upstream">
+ <title>Upgrading to a new upstream release</title>
+ <para>
+ <command>git-buildpackage</command>'s command
+ <command>git-import-orig</command> makes it easy to update of the
+ <emphasis>upstream</emphasis> branch using upstream releases
+ distributed as a compressed archive, and to merge these changes in
+ the <emphasis>master</emphasis> branch. Its option
+ <command>--pristine-tar</command> is useful for stabilizing the MD5 sum
+ of the "<filename>orig.tar.gz</filename>" produced when building a
+ source package from the repository alone (not doing so results in
+ archive rejection of package updates). With recent versions of
+ <command>git-buildpackage</command>, it is often unnecessary to rename
+ the freshly downloaded original upstream archive.
+ </para>
+ <para>
+ If you do not use <command>git-buildpackage</command>, please use
+ <command>pristine-tar</command> anyway to register the compressed
+ archives that you upload to Debian as original upstream sources
+ (the <literal>orig.tar.{gz|bz2|xz}</literal> file), with a command
+ such as the following, where <replaceable><tarball></replaceable>
+ is a path to the archive file and
+ <replaceable><tag></replaceable> is the upstream release tag
+ for that archive (as a fallback, if you created the tarball from a
+ given branch, use the name of the branch).
+<programlisting>
+<command>pristine-tar commit</command> <option><replaceable><tarball></replaceable></option> <option><replaceable><tag></replaceable></option>
+</programlisting>
+ </para>
+ </sect4>
+ <sect4 id="git-build-package">
+ <title>Building the package</title>
+ <para>
+
+ </para>
+ </sect4>
+ <sect4 id="git-repository-layout">
+ <title>Repository layout</title>
+ <para>
+
+ </para>
+ </sect4>
+ <sect4 id="git-push">
+ <title>Pushing to git.debian.org</title>
+ <para>
+
+ </para>
+ </sect4>
+ </sect3>
+ <sect3 id="git-package-branches">
+ <title>Branches</title>
+ <para>
+
+ </para>
+ </sect3>
+ <sect3 id="git-patches">
+ <title>Patches</title>
+ <para>
+
+ </para>
+ </sect3>
+ <sect3 id="git-commit-policy">
+ <title>Commit policy</title>
+ <para>
+
+ </para>
+ </sect3>
+ <sect3 id="git-remove-package">
+ <title>Removing packages</title>
+ <para>
+
+ </para>
+ </sect3>
+ <sect3 id="git-tips">
+ <title>Tips & tricks</title>
+ <sect4 id="git-options-devscripts">
+ <title>
+ Set the <package>devscripts</package> variables
+ <varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname>
+ </title>
+ <para>
+ <command>debcheckout</command> will then set <command>git</command>'s
+ options <varname>user.email</varname> and <varname>user.name</varname>
+ accordingly.
+ </para>
+ </sect4>
+ <sect4 id="debcheckout-sets-git-options">
+ <title>Configure Git to commit using your packager name and address.</title>
+ <para>
+ The <option>--global</option> option is to say Git these are the
+ default parameters for every Git repository you commit to,
+ without it the settings will be per-repository only:
+ </para>
+ <para>
+<programlisting>
+<command>git config</command> <option><optional>--global</optional></option> <option>user.name "$DEBFULLNAME"</option>
+<command>git config</command> <option><optional>--global</optional></option> <option>user.email "$DEBEMAIL"</option>
+</programlisting>
+ </para>
+ </sect4>
+ <sect4 id="new-repository-with-gbp">
+ <title>To create a new local git repository</title>
+ <para>
+ When the upstream sources are distributed as compressed
+ <command>tar</command> archives (<literal>tar.gz</literal>, …):
+ </para>
+ <para>
+<programlisting>
+<command>mkdir</command> <replaceable><package></replaceable>
+<command>cd</command> <replaceable><package></replaceable>
+<command>git init</command>
+<command>git import-orig</command> <option>--pristine-tar</option> <filename><replaceable>/path/to/package_version.orig.tar.gz</replaceable></filename>
+<command>dh_make</command> <option>-p <replaceable>package_x.y.z</replaceable></option>
+</programlisting>
+ </para>
+ <para>
+ The above steps will create a repository with the appropriate layout
+ for <command>git-buildpackage</command>, with three branches:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>master</literal>,
+ where the Debian development will happen,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pristine-tar</literal>, used by the
+ <command>pristine-tar</command> tool during the package build
+ process to recreate the original tarball, and
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>upstream</literal>,
+ which will contain the upstream source.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect4>
+ <sect4 id="debcheckout-git-track">
+ <title>To clone and follow every branch of a git repository.</title>
+ <para>
+ When the package is already in the Debian archive, you can use the
+ <command>debcheckout</command> command with its
+ <option>--git-track='*'</option> option.
+ </para>
+ <para>
+ To update the <literal>master</literal>, <literal>upstream</literal>
+ and <literal>pristine-tar</literal> branches at once, use the
+ <command>gbp-pull</command>.
+ </para>
+ </sect4>
+ <sect4 id="git-track-new-branches">
+ <title>To track extra upstream branches, simply check them out.</title>
+ <para>
+ With recent versions of git, the remote branch will be automatically
+ tracked when running <command>git</command> checkout.
+ </para>
+ <para>
+ For example, when a <literal>pristine-tar</literal> branch is
+ available upstream and not yet tracked locally, the command
+ <command>git checkout</command> <option>pristine-tar</option>
+ will implicitely run the command
+ <command>git branch</command> <option>-t pristine-tar origin/pristine-tar</option>.
+ </para>
+ </sect4>
+ <sect4 id="create-git-repository-on-alioth">
+ <title>Pushing to git.debian.org, creating a new bare repository on Alioth.</title>
+ <para>
+ Before pushing to git.debian.org for the first time,
+ an empty repository needs to be created there.
+ </para>
+ <para>
+ To do this connect to <literal>git.debian.org</literal>, enter the
+ <filename class="directory">/git/pkg-grass</filename> directory,
+ and run the <command>./setup-repository</command> script.
+ </para>
+ <para id="example-create-bare-git-repository-on-alioth">
+ Run it similar to:
+<programlisting>
+<command>ssh</command> git.debian.org
+<command>cd</command> /git/pkg-grass
+<command>./setup-repository</command> <replaceable><package></replaceable> 'Packaging of <replaceable><package></replaceable> in Debian'
+</programlisting>
+ </para>
+ <para>
+ This will create an empty, bare, shared Git repository and setup some
+ hooks. Each package is kept in its own Git repository.
+ </para>
+ <para>
+ Now, on your local machine add the Alioth repository as a remote:
+ </para>
+ <para>
+<programlisting>
+<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://git.debian.org/git/pkg-grass/<package>.git</filename>
+</programlisting>
+ </para>
+ <para>
+ This is done automatically after cloning a repository, for instance
+ with <link linkend="debcheckout-git-track">debcheckout</link>.
+ The default remote branch is called <quote>origin</quote>.
+ </para>
+ </sect4>
+ <sect4 id="git-change-default-branch">
+ <title>To change the default branch.</title>
+ <para>
+ If the Debian work is not on the <literal>master</literal> branch,
+ change the default branch by editing the <filename>HEAD</filename>
+ file in the bare repository on Alioth, and replace
+ <literal>master</literal> by the name of the new default branch.
+ For a branch called <literal>debian/unstable</literal> the contents
+ of the file will be <literal>refs/heads/debian/unstable</literal>.
+ </para>
+ </sect4>
+ <sect4 id="push-package-to-alioth">
+ <title>To push the package.</title>
+ <para>
+ (make sure you've added the alioth remote!), do the following:
+ <command>git push</command> <option>origin master</option>.
+ For the first push, it's necessary to specify
+ <option>origin master</option>. The next time you will push, a
+ <command>git push</command> will suffice.
+ </para>
+ <para>
+ Or use the <option>--set-upstream</option> option, helps future use of
+ <command>git pull</command>.
+<programlisting>
+<command>git</command> push --set-upstream
+</programlisting>
+ </para>
+ </sect4>
+ <sect4 id="git-push-all-tags">
+ <title>To push all your work</title>
+ <para>
+ Be sure to also do a run <command>git push</command> with
+ <option>--all</option>, and one with <option>--tags</option>
+ if you created new tags.
+<programlisting>
+<command>git</command> push --all --set-upstream
+<command>git</command> push --tags
+</programlisting>
+ </para>
+ </sect4>
+ <sect4 id="git-tag-release">
+ <title>To tag a release</title>
+ <para>
+ <command>git tag</command> <option>debian/x.y-z</option>.
+ You can also easily retroactively make tags:
+ <command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option>.
+ Remember to <command>git push --tags</command>.
+ </para>
+ </sect4>
+ <sect4 id="git-debian-version-from-commit">
+ <title>If upstream manages his sources with Git.</title>
+ <para>
+ The following makefile script can help producing a version number
+ when no Git tag is available:
+<programlisting>
+SOURCEPKG=$(shell dpkg-parsechangelog | sed -n 's/^Source: \(.*\)/\1/p')
+UPSTREAM=$(shell dpkg-parsechangelog | sed -n 's/^Version: \(.*\)-[^-]*/\1/p')
+SHA1=$(lastword $(subst ~g, ,$(UPSTREAM)))
+ORIG=${SOURCEPKG}_${UPSTREAM}.orig.tar.gz
+
+describe-current-version:
+ git describe --tags upstream | sed 's,^release-,,;s,-,+,;s,-,~,;'
+
+get-orig-source:
+ git archive --format=tar $(SHA1) | gzip -9 > ../$(ORIG)
+</programlisting>
+ </para>
+ </sect4>
+ <sect4 id="git-pbuilder">
+ <title>
+ To make <command>git-buildpackage</command> build the package
+ with <command>pdebuild</command>.
+ </title>
+ <para>
+ Add the following to the configuration file
+ <filename>~/.gbp.conf</filename> or
+ <filename>debian/gbp.conf</filename>:
+<programlisting>
+[DEFAULT]
+builder = ~/bin/git-pbuilder
+</programlisting>
+ With this configuration file you're specifying that
+ <command>git-buildpackage</command> will use
+ <filename>~/bin/git-pbuilder</filename> as the builder script.
+ This is an example script you can use:
+<programlisting>
+#!/bin/sh
+set -e
+
+pdebuild --pbuilder cowbuilder --debbuildopts "-i\.git -I.git $*"
+rm ../*_source.changes
+</programlisting>
+ This will build the package inside the default cowbuilder chroot,
+ while passing any more parameters directly do
+ <command>dpkg-buildpackage</command>.
+ </para>
+ </sect4>
+ </sect3>
+ </sect2>
+ <sect2 id="svn-packaging">
+ <title>Packaging with Subversion</title>
+ <para>
+
+ </para>
+ <sect3 id="subversion-tips">
+ <title>Subversion tips</title>
+ <para id="svn-buildpackage-aliases">
+ Suggested aliases for <command>svn-buildpackage</command>:
+<programlisting>
+alias <command>svn-b</command>='svn-buildpackage -us -uc --svn-ignore'
+alias <command>svn-br</command>='svn-b --svn-dont-purge --svn-reuse'
+alias <command>svn-bt</command>='svn-buildpackage --svn-tag'
+</programlisting>
+ </para>
+ <para id="svn-mergewithupstream">
+ <command>svn-inject <replaceable>-o</replaceable></command> sets up the
+ <literal>mergeWithUpstream</literal> property for the SVN directories
+ where packages are stored. In case <command>svn-inject</command>
+ was not used, you can do it by hand with the command
+ <command>svn propset</command>
+ <replaceable>mergeWithUpstream</replaceable>
+ <replaceable>1</replaceable> <replaceable>debian</replaceable>.
+ </para>
+ <para id="download-upstream-source">
+ To download the upstream sources (if there is a
+ <filename>debian/watch</filename> file):
+ <command>echo "origDir=.." >> .svn/deb-layout && uscan --force-download</command>.
+ Alternatively, you can try
+ <command>debian/rules get-orig-source</command>.
+ </para>
+ <para id="svn-write-access">
+ If you're a Debian Developer or a member of the pkg-grass group on
+ Alioth, you can commit your changes: <command>svn commit</command>
+ (also <command>svn ci</command>). Otherwise, you can ask to be added
+ to the group (see the <link linkend="membership">Membership</link>
+ section), or send the result of <command>svn diff</command> to the
+ <ulink url="mailto:debian-gis at lists.debian.org">mailing list</ulink>
+ (<command>gzip -9</command> it, if it's too large).
+ </para>
+ <para id="svn-tag-release">
+ It may happen that a package version has been uploaded to Debian
+ repositories, and you forgot to tag the last build with
+ <command>svn-buildpackage --svn-tag</command>. You can tag this
+ package also retroactively. A first step, creating the tags directory,
+ can be achieved in two ways: either create it locally as sibling of
+ <filename class="directory">trunk/</filename> with
+ <command>svn mkdir</command>
+ <filename class="directory">tags</filename>, and commit with
+ <command>svn commit</command>, or create it remotely with
+ <command>svn mkdir</command>
+ <filename class="directory">svn+ssh://<user>@svn.debian.org/svn/pkg-grass/packages/<package>/tags</filename>.
+ After the tags directory has been created, you're ready to tag the
+ package: <command>svn-buildpackage</command>
+ <option>--svn-tag-only</option> <option>--svn-no-autodch</option>.
+ The <option>--svn-no-autodch</option> avoids
+ <filename>debian/changelog</filename> to be marked as
+ <literal>UNRELEASED</literal>.
+ </para>
+ <para id="example-svn-session">
+ Here is an example session where a package is prepared manually:
+<programlisting>
+# Check out pkg-grass, cd to pkg-grass/packages
+# Create new project folder with
+svn mkdir projectname
+svn mkdir projectname/trunk
+
+# Put orig.tar.gz in place
+mv some_version.orig.tar.gz projectname
+
+# Inform svn-buildpackage about the location of the orig.tar.gz
+echo "origDir=.." > projectname/trunk/.svn/deb-layout
+
+# Untar source tree for development
+cd projectname
+tar xzvf some_version.orig.tar.gz
+cd some-version # entering the unpackaged source tree
+if [ ! -d debian ]; then dh_make ; fi
+mv debian ../trunk
+ln -s ../trunk/debian .
+
+# continue development
+fakeroot ./debian/rules binary
+
+# until it works, finally
+cd ..
+
+# debian directory is the only thing that is stored in svn, to be merged with upstream svn propset merge with upstream
+svn propset mergeWithUpstream 1 trunk/debian
+
+# See if things can be compiled via svn-buildpackage
+cd trunk
+svn-buildpackage -uc -us
+
+# check build
+lintian ../build-area/*changes
+</programlisting>
+ </para>
+ </sect3>
+ </sect2>
<sect2 id="backports">
<title>Backports</title>
<para>
Debian offers <ulink url="http://backports.debian.org">backports</ulink>
to its stable version. Backports of Debian GIS packages should be kept
as branches in our
- <link linkend="git-repository-structures">Git</link> or
- <link linkend="svn-repository-structure">Subversion</link> repositories.
+ <link linkend="git-repository">Git</link> or
+ <link linkend="svn-repository">Subversion</link> repositories.
</para>
</sect2>
<sect2 id="ubuntugis-ppa">
--
pkg-grass website
More information about the Pkg-grass-devel
mailing list