[SCM] website branch, master, updated. 437ced3d8642ad6c9536e57c6fdf702dde555970
Bas Couwenberg
sebastic at xs4all.nl
Sun Jan 5 19:34:20 UTC 2014
The following commit has been merged in the master branch:
commit 437ced3d8642ad6c9536e57c6fdf702dde555970
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date: Sun Jan 5 20:25:39 2014 +0100
Improve Introduction, How to Contribute and Membership sections.
Improvements to the Introduction, How to Contribute and Membership sections
are made to be better describe the relation of Debian GIS to its derivatives,
specifically UbuntuGIS and OSGeo-Live.
The Git repository section is better formatted to describe the commonly used
branches and tags.
The Upstream Git repositories section is extended to further describe working
with upstream Git repositories, and the consequences for packaging.
The build-essential and devscripts packages are now included in the Tools
section.
Various syntax changes for improved output formatting.
diff --git a/policy.xml b/policy.xml
index 20f8603..468a86c 100644
--- a/policy.xml
+++ b/policy.xml
@@ -61,20 +61,30 @@
exciting GIS packages in Debian's main archives. Other programs
are well along their way to being included in the archive.
</para>
+ <para>
+ The Debian source packages maintained by the Debian GIS team are also
+ used by efforts to support current GIS software on Debian derivatives
+ such as <ulink url="https://wiki.ubuntu.com/UbuntuGIS">UbuntuGIS</ulink>,
+ which provides backports of GIS packages for Ubuntu,
+ and <ulink url="http://live.osgeo.org/">OSGeo-Live</ulink> for their
+ Ubuntu based distribution.
+ </para>
</sect1>
<sect1 id="contribute">
<title>How to Contribute</title>
<para>
From the developer to the user, there is a long chain of tasks in which
- we always welcome participation. First we must keep ourselves informed
- about the software landscape in GIS and OpenStreetMap. Software to be
- packaged is chosen according to criteria such as users' need and the
- consistency of the distribution.
+ we always welcome participation.
+ First we must keep ourselves informed about the software landscape in
+ GIS and/or OpenStreetMap.
+ Software to be packaged is chosen according to criteria such as users'
+ need and the consistency of the distribution.
</para>
<para>
Once in Debian, the software is monitored for its quality and bugs are
fixed, if possible in collaboration with the upstream maintainer(s).
- All this work would not be very useful if it remains confidential.
+ All this work would not be very useful if it remains confidential or
+ confined to the source packages of Debian and its derivative distributions.
</para>
<para>
We also dedicate some time to advertise it to the world via
@@ -84,8 +94,10 @@
<para>
Please contact us on
<ulink url="mailto:debian-gis at lists.debian.org">debian-gis at lists.debian.org</ulink>
- if you want to help to make GIS and OpenStreetMap software available to
- Debian users. Read the <link linkend="membership">Membership</link>
+ if you want to help to make GIS and/or OpenStreetMap software available to
+ users of Debian and its derivative distributions such as Ubuntu,
+ OGeo-Live, Mint, etc.
+ Read the <link linkend="membership">Membership</link>
section if you're interested in joining us.
</para>
<para>
@@ -111,13 +123,26 @@
<sect2 id="membership">
<title>Membership</title>
<para>
- To request membership to this group, please go on our
- <ulink url="http://alioth.debian.org/projects/pkg-grass">Alioth page</ulink>,
- or directly follow this
- <ulink url="https://alioth.debian.org/project/request.php?group_id=30241">link</ulink>.
- Remember that you must have an Alioth account before requesting membership (see
- <ulink url="http://alioth.debian.org/account/register.php">here</ulink>
- to request an Alioth account).
+ To request for membership of the Debian GIS team, and access to our collaboration
+ infrastructure on Alioth, please go to our
+ <ulink url="http://alioth.debian.org/projects/pkg-grass">Alioth page</ulink>
+ or directly follow the
+ <ulink url="https://alioth.debian.org/project/request.php?group_id=30241">Request to join</ulink>
+ link.
+ </para>
+ <para>
+ You need to register an Alioth account before you can request for
+ membership of the Debian GIS team, by submitting the
+ <ulink url="http://alioth.debian.org/account/register.php">User Account Registration</ulink>
+ form.
+ </para>
+ <para>
+ The Debian GIS team collaboration infrastructure on Alioth originates
+ from the initial team effort to maintain the <literal>grass</literal>
+ package.
+ It has since grown to collaboratively maintain most GIS and
+ OpenStreetMap source packages, but still uses the
+ <literal>pkg-grass</literal> group name on Alioth.
</para>
</sect2>
<sect2 id="readings">
@@ -268,53 +293,76 @@ pkg-grass/
└ master
</programlisting>
</para>
- <para>
- Upstream sources are kept (in plain, uncompressed form) in the
- <literal>upstream</literal> branch.
- The data needed to regenerate original source tarballs from the
- <literal>upstream</literal> branch are kept with the help of the
- <command>pristine-tar</command> tool in the
- <literal>pristine-tar</literal> branch.
- Upstream sources are merged with Debian-specific changes in the
- <literal>master</literal> branch, which is the usual place to work in.
- </para>
- <para>
- In case updates to packages in stable are made and the master branch
- already uses a newer upstream release, using dedicated branches for the
- older version in Debian named after the release codename is recommended.
- </para>
- <para>
- Using Ubuntu release specific branches assist collaboration between the
- DebianGIS and UbuntuGIS teams. Changes from Debian or Ubuntu can be
- merged or cherry picked from their respective branches without having to
- copy them from the source packages.
- </para>
- <para>
- From this point on, work on the package normally. Some prefer to update
- <filename>debian/changelog</filename> with each commit, others leave
- this to the <command>git-dch</command> tool at package release time.
- In case you use <command>git-dch</command> for the changelog entries,
- don't forget to use it when you stop working on the package.
- </para>
<sect3 id="git-branches">
<title>Common Git branches</title>
<para>
Most of our packages using Git and stored in Alioth are managed
following the standard layout of the
<command>git-buildpackage</command> helper.
- The <literal>master</literal> branch contains the full source package.
- The <literal>upstream</literal> branch contains the upstream source,
- after repacking when necessary (non-free files, large convenience code
- copies, …).
- The <literal>pristine-tar</literal> branch contains the data necessary
- to recreate an original tarball from the repository with a
- reproducible checksum.
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>master</literal> branch contains the full source package.
+ </para>
+ <para>
+ Upstream sources are merged with Debian-specific changes in the
+ <literal>master</literal> branch, which is the usual place to work in.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>pristine-tar</literal> branch contains the data necessary
+ to recreate an original tarball from the repository with a
+ reproducible checksum.
+ </para>
+ <para>
+ The data needed to regenerate original source tarballs from the
+ <literal>upstream</literal> branch are kept with the help of the
+ <command>pristine-tar</command> tool in the
+ <literal>pristine-tar</literal> branch.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>upstream</literal> branch contains the upstream source,
+ after repacking when necessary (non-free files, large convenience code
+ copies, …).
+ </para>
+ <para>
+ Upstream sources are kept (in plain, uncompressed form) in the
+ <literal>upstream</literal> branch.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- Debian releases are tagged with names like
- <literal>debian/debianversion</literal>
- and upstream releases are tagged with names like
- <literal>upstream/upstreamversion</literal>.
+ The standard tagging convention used by the Debian GIS team is:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>upstream/<replaceable><upstreamversion></replaceable></literal>
+ for upstream releases
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>debian/<replaceable><debianversion></replaceable></literal>
+ for Debian releases
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ubuntu/<replaceable><ubuntuversion></replaceable></literal>
+ for UbuntuGIS releases
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>osgeo/<replaceable><osgeoversion></replaceable></literal>
+ for OSGeo-Live releases
+ </para>
+ </listitem>
+ </itemizedlist>
</para>
<para>
<command>git-buildpackage</command> can be set to a directory layout
@@ -328,12 +376,18 @@ pkg-grass/
<sect3 id="other-git-branches">
<title>Other Git branches</title>
<para>
- Changes uploaded to other distributions than
+ Changes uploaded to other distributions than Debian
<literal>unstable</literal> can be stored in other branches,
named for instance <literal>experimental</literal>,
<literal>jessie</literal>, etc.
</para>
<para>
+ This is usefull in case updates to packages in stable are made and
+ the master branch already uses a newer upstream release.
+ Using dedicated branches for the older version in Debian named after
+ the release codename is recommended.
+ </para>
+ <para>
Packaging for the
<link linkend="ubuntugis-ppa">UbuntuGIS PPA</link> is encouraged to
be stored in Ubuntu release specific branches such as
@@ -349,9 +403,17 @@ pkg-grass/
<literal>osgeo/7.0</literal>,
<literal>osgeo/8.0</literal>, etc.
</para>
+ <para>
+ Using UbuntuGIS and derivative release specific branches assist
+ collaboration between Debian GIS and the UbuntuGIS and derivative
+ teams.
+ Changes from Debian or Ubuntu can be merged or cherry picked from
+ their respective branches without needing to obtain the source
+ packages to manually merge the changes from.
+ </para>
</sect3>
- <sect3 id="git-without-tarball">
- <title>Social Git</title>
+ <sect3 id="git-upstream-repositories">
+ <title>Upstream Git repositories</title>
<para>
For some projects, like the ones hosted on
<ulink url="http://www.github.com">GitHub</ulink> or
@@ -371,6 +433,20 @@ pkg-grass/
<link linkend="debian-gbp.conf"><filename>debian/gbp.conf</filename></link>,
to document the layout of the repository.
</para>
+ <para>
+ When working with upstream Git repositories, it's convenient to have
+ the upstream repository configured as a Git remote called
+ <literal>upstream</literal>.
+ Fetching the upstream commit history into the package repository
+ allows among others per commit reviews of new upstream releases,
+ and reading extended commit messages.
+ </para>
+ <para>
+ When the upstream Git repository is not configured as a remote in the
+ Debian GIS Git repository on Alioth, you may not want to push the
+ upstream tags, because the references commits only exist in the
+ upstream Git repository.
+ </para>
</sect3>
</sect2>
<sect2 id="svn-repository">
@@ -524,6 +600,21 @@ pkg-grass/
<itemizedlist>
<listitem>
<para>
+ <command>build-essential</command> depends on the essential
+ packages required for every kind of Debian package development.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>devscripts</command> provides
+ <command>debcheckout</command>, <command>debcommit</command>,
+ <command>debuild</command>, <command>uscan</command>,
+ <command>licensecheck</command>, and many other commonly used
+ programs in the Debian source packaging workflow.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<command>git-buildpackage</command> and its helper tools
are used by most source packages maintained as Git repositories
in Debian GIS.
@@ -792,43 +883,59 @@ pkg-grass/
<para>
...
</para>
+ <para>
+ From this point on, work on the package normally.
+ Some prefer to update <filename>debian/changelog</filename> with
+ each commit using the <command>dch</command> command,
+ others leave this to the <command>git-dch</command> tool
+ at package release time.
+ In case you use <command>git-dch</command> for the changelog entries,
+ don't forget to use it when you stop working on the package.
+ </para>
</sect4>
<sect4 id="git-push">
<title>Pushing to git.debian.org</title>
<para>
Before pushing your packaging changes to git.debian.org for the
first time, an empty repository needs to be created there.
+ And you need to configure a Git remote for the repository on Alioth.
</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="create-git-repository-on-alioth">
- Run it similar to:
+ <sect5 id="create-git-repository-on-alioth">
+ <title>Create a Git repository on Alioth</title>
+ <para>
+ To create a Git repository on Alioth, 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>
<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>
+ </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>
+ </sect5>
+ <sect5 id="git-alioth-remote">
+ <title>Configure a Git remote for the repository</title>
+ <para>
+ 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>
+ </para>
+ <para>
+ This is done automatically after cloning a repository, for instance
+ with <link linkend="debcheckout-git-track">debcheckout</link>.
+ The default remote repository is called <quote>origin</quote>.
+ </para>
+ </sect5>
<sect5 id="push-package-to-alioth">
<title>To push the package</title>
<para>
@@ -1118,10 +1225,13 @@ lintian ../build-area/*changes
<ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version">inferior in version by using a tilde</ulink>.
If the package contains additional development, a version number without
the tilde will make it higher, but not as high as the next Debian
- revision. For example: <code>2.12.0-1~natty1</code> (backport in PPA)
- < <code>2.12.0-1</code> (from Debian in Ubuntu)
- < <code>2.12.0-1natty1</code> (in PPA, containing additions)
- < <code>2.12.0-2</code> (from Debian in Ubuntu).
+ revision. For example:
+<programlisting>
+ 2.12.0-1~natty1 (backport in PPA)
+< 2.12.0-1 (from Debian in Ubuntu)
+< 2.12.0-1natty1 (in PPA, containing additions)
+< 2.12.0-2 (from Debian in Ubuntu).
+</programlisting>
</para>
<para>
Packages sent to the UbuntuGIS PPAs may be kept as
--
pkg-grass website
More information about the Pkg-grass-devel
mailing list