Author: plessy
Date: 2011-03-19 08:53:42 +0000 (Sat, 19 Mar 2011)
New Revision: 6306
Modified:
trunk/community/website/docs/policy.xml
Log:
Added IDs to ease navigation in jEdit.
Modified: trunk/community/website/docs/policy.xml
===================================================================
--- trunk/community/website/docs/policy.xml 2011-03-19 05:41:55 UTC (rev
6305)
+++ trunk/community/website/docs/policy.xml 2011-03-19 08:53:42 UTC (rev
6306)
@@ -38,7 +38,7 @@
<imagedata fileref="/img/debian-med.jpg" format="JPG"
align="center" />
</imageobject>
</mediaobject>
- <sect1>
+ <sect1 id="introduction">
<title>Introduction</title>
<para>Debian Med is a <quote><ulink
url="http://blends.alioth.debian.org/blends";>Debian Pure Blend</ulink></quote>
with the aim to develop Debian into an operating system that is
particularly
@@ -52,7 +52,7 @@
Debian Med is not a competition to these efforts but a platform
to
present the packages to the community as a Debian Pure
Blend.</para>
</sect1>
- <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
@@ -78,8 +78,8 @@
guide Debian users towards the use of packages to their
immediate benefit.
You may also consider to write respective articles for
Magazines, be they
online or in print.</para>
- <sect2>
- <title id="membership">Membership</title>
+ <sect2 id="membership">
+ <title>Membership</title>
<para>To request membership to this group, please go on
our
<ulink
url="http://alioth.debian.org/projects/debian-med";>Alioth page</ulink>,
or directly follow this <ulink
url="http://alioth.debian.org/project/request.php?group_id=30063";>link</ulink>.
@@ -87,8 +87,8 @@
membership (see <ulink
url="http://alioth.debian.org/account/register.php";>here</ulink>
to request an Alioth account).</para>
</sect2>
- <sect2>
- <title id="readings">Essential readings</title>
+ <sect2 id="readings">
+ <title>Essential readings</title>
<itemizedlist>
<listitem><para>The <ulink
url="http://www.debian.org/doc/debian-policy/";>Debian Policy</ulink>: packages
must conform to it.</para></listitem>
<listitem><para>The <ulink
url="http://www.debian.org/doc/developers-reference/";>Developers
Reference</ulink>: details best packaging practices.</para></listitem>
@@ -97,7 +97,7 @@
</itemizedlist>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="repositories">
<title>Repositories</title>
<para>We use Subversion (SVN) and Git repositories, hosted on
<ulink url="http://alioth.debian.org/";>Alioth</ulink>, the
hosting
@@ -112,7 +112,7 @@
Git or git-buildpackage are desired, or more simply when the
maintainer wants
to thake the opportunity to familiarise with Git.
</para>
- <sect2>
+ <sect2 id="source">
<title>Give me the source!</title>
<para>
To check sources out from our repostitories,
please do:
@@ -155,7 +155,7 @@
package.
</para>
</sect2>
- <sect2>
+ <sect2 id="repository-structure">
<title>Repository structure</title>
<para>The SVN repository is structured as follows:
<literallayout>
@@ -187,7 +187,7 @@
<para>The Git repository is not structured: each
package is in its own Git repository.
But all of them are under the same
<filename>debian-med</filename> directory.</para>
</sect2>
- <sect2>
+ <sect2 id="subversion-to-git">
<title>Migration of a source package from Subversion to
Git.</title>
<para>There is no easy way to prepare a Git repository from
our Subversion repository that would
look like the package was always managed in Git,
because we use svn-buildpackage with the
@@ -210,15 +210,15 @@
</itemizedlist>
<para>It is also possible to prepare a Git repository
containing some of the package's history using the command
<command>git-import-dscs --debsnap</command> from the helper toolkit
<command>git-buildpackage</command>. This will download all the versions of a
package available in <ulink
url="http://snapshot.debian.org";>snapshots.debian.org</ulink> and create tags
for each of them. Note that as this paragraph is written, the tool is not aware
that <emphasis>backports</emphasis> should be a different branch</para>
</sect2>
- <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 Med 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> allows very easy update of the
<emphasis>upstream</emphasis> branch when the original sources are distributed
as a compressed archive. Its option <command>--pristine-tar</command> is useful
for stablizing 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
git-buildpackage, it is often unnecessary to rename the freshly downloaded
original upstream archive.</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="packaging">
<title>Packaging</title>
- <sect2>
+ <sect2 id="itp">
<title>Announcing intent to package</title>
<para>If you intent to work on a Debian package you
should follow
the <ulink
url="http://www.debian.org/devel/wnpp/#l1";>normal Debian rules</ulink> and file
a <acronym>WNPP</acronym> bug report.</para>
@@ -231,15 +231,15 @@
the best, and document your ITP number using the
<command>WNPP</command> field name.</para>
</sect2>
</sect1>
- <sect1>
+ <sect1 id="tasks">
<title>Tasks</title>
<para>The Debian Med <ulink
url="http://blends.alioth.debian.org/blends";>Debian Pure Blend</ulink> is
organised by <ulink
url="http://debian-med.alioth.debian.org/tasks/index";>tasks</ulink>, that group
packages around broad themes such as <ulink
url="http://debian-med.alioth.debian.org/tasks/imaging";>medical imaging</ulink>
for instance. The tasks list programs that are already packaged in Debian as
well as packages in preparation.</para>
<para>The tasks files are not hosted in the Debian Med
repositories, but in the Debian Blends repository. Nevertheless, all members of
the Debian Med project on the Alioth forge have write access to the Blends
subversion repository. You can easily check out its sources with the command
<command>debcheckout -a debian-med</command>.</para>
<para>The syntax of the tasks files is very similar to Debian
control files, and described in the <ulink
url="http://blends.alioth.debian.org/blends/ch-sentinel.en.html";>Debian Blends
website</ulink>.</para>
</sect1>
- <sect1>
+ <sect1 id="policy">
<title>Policy</title>
- <sect2>
+ <sect2 id="debian-control">
<title><filename>debian/control</filename></title>
<orderedlist>
<listitem>
@@ -310,34 +310,34 @@
</orderedlist>
</sect2>
- <sect2>
+ <sect2 id="debian-copyright">
<title><filename>debian/copyright</filename></title>
<para>We use the <ulink
url="http://wiki.debian.org/Proposals/CopyrightFormat";>proposed
machine-readable format</ulink> for the <filename>debian/copyright</filename>
file. The <computeroutput>Source</computeroutput> field does not need to
contain the full URL to the particular version that is being packaged, since
this can be determined by the <command>uscan</command> program with the
<filename>debian/watch</filename> file. Please list yourself in the
<computeroutput>Files: debian/*</computeroutput> section if you think that your
contributions are not trivial and therefore subjected to copyright. Please
chose a license that is compatible with the program you package. You can also
use <quote>same as if it were in the public domain</quote> or <quote>same as
the packaged program itself</quote>.</para>
</sect2>
- <sect2>
+ <sect2 id="debian-changelog">
<title><filename>debian/changelog</filename></title>
<para>Packages hosted in our Subversion repository,
that have been modified but not uploaded must use
<emphasis>UNRELEASED</emphasis> as a distribution name. This can be done
automatically by declaring
<emphasis>DEBCHANGE_RELEASE_HEURISTIC=changelog</emphasis> in
<filename>~/.devscripts</filename> and using <command>dch</command>.</para>
</sect2>
- <sect2>
+ <sect2 id="debian-readme-source">
<title><filename>debian/README.source</filename></title>
<para>This file is recommended by the Policy (<ulink
url="http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource";>§ 4.14</ulink>)
from version 3.8.0 for documenting source package handling. Please follow the
recommendation. For instance, this file is needed when we use a patch system,
when the upstream sources are in another format than gzipped tar achive, when
we repack the sources,…</para>
</sect2>
- <sect2>
+ <sect2 id="debhelper">
<title>Debhelper</title>
<para>Debhelper uses compatibility levels to control
the behaviour of its commands. The latest level is not always available in
<emphasis>Stable</emphasis> or <emphasis>Backports</emphasis>. Please avoid
using it unless needed until it is available, to facilitate backporting. We
currently recommend to use the level <emphasis>7</emphasis>.</para>
</sect2>
- <sect2>
+ <sect2 id="cdbs">
<title>CDBS</title>
<para>The use of CDBS is welcome as it helps us to
factorise our code. Nevertheless, please do not use complex CDBS for
non-trivial packages, so that other developers can quickly understand the
package when doing QA work.</para>
<para>It is technically possible to build CDBS packages
using Debhelper without the <filename>debian/compat</filename> file. Please do
not, and always include such a file according to the above guidelines.</para>
</sect2>
- <sect2>
+ <sect2 id="new-package">
<title>Injecting a new package</title>
- <sect3>
+ <sect3 id="svn-inject">
<title>Subversion</title>
<para>To inject a new package to the SVN repository,
you must have
write access to it; i.e. you must be a member of the
<emphasis>debian-med</emphasis> group on Alioth.</para>
@@ -360,9 +360,9 @@
the Debian Med packaging pool but it helps if the
maintainer of a
certain package verifies that everything is in the
right place.</para>
</sect3>
- <sect3>
+ <sect3 id="new-git-repository">
<title>Git</title>
- <sect4>
+ <sect4 id="git-buildpackage">
<title>Creating a local repository</title>
<para>Just a few instructions to get you started:</para>
<blockquote>
@@ -422,7 +422,7 @@
</blockquote>
<para>The next step is to create the remote repository on
Alioth.</para>
</sect4>
- <sect4>
+ <sect4 id="create-alioth-repository">
<title>Creating the remote repository</title>
<blockquote>
<para><userinput>
@@ -442,7 +442,7 @@
<para>This will create a <filename
class="directory">packagename.git</filename> repository on
Alioth, with the proper hooks set up for our team.</para>
</sect4>
- <sect4>
+ <sect4 id="push-package-to-alioth">
<title>Pushing the package</title>
<para>To push the package (make sure you've added the
alioth remote!), do the following:</para>
<blockquote>
@@ -466,11 +466,11 @@
</sect4>
</sect3>
</sect2>
- <sect2>
+ <sect2 id="building-and-tagging">
<title>Building and tagging the packages</title>
- <sect3>
+ <sect3 id="building">
<title>Building the packages</title>
- <sect4>
+ <sect4 id="building-subversion">
<title>Subversion</title>
<para>To build the package, just use the tools that
<command>svn-buildpackage</command>
carries. First of all, we suggest you to define some
aliases for the
@@ -510,7 +510,7 @@
<ulink url="mailto:[email protected]";>mailing
list</ulink>
(<command>gzip -9</command> it, if it's too
large).</para>
</sect4>
- <sect4>
+ <sect4 id="building-git">
<title>Git</title>
<para>You should use <command>git-buildpackage</command> to
build the
packages with git. Be sure to run it from the
<quote>master</quote>
@@ -545,9 +545,9 @@
passing any more parameters directly do
<command>dpkg-buildpackage</command>.</para>
</sect4>
</sect3>
- <sect3>
+ <sect3 id="tagging">
<title>Tagging packages</title>
- <sect4>
+ <sect4 id="tagging-subversion">
<title>Subversion</title>
<para>It may happen that a package version has been
uploaded to Debian
repositories, and you forgot to tag the last build
with</para>
@@ -590,7 +590,7 @@
</blockquote>
<para>(--svn-no-autodch avoids
<filename>debian/changelog</filename> to be marked as UNRELEASED).</para>
</sect4>
- <sect4>
+ <sect4 id="tagging-git">
<title>Git</title>
<para>Tagging a release with git is pretty
straightforward:</para>
<blockquote>
@@ -616,7 +616,7 @@
</sect4>
</sect3>
</sect2>
- <sect2>
+ <sect2 id="patches">
<title>Handling patches</title>
<para>Often happens that the upstream code doesn't fit
well into the
Debian distribution: be this wrong paths, missing
features, anything
@@ -627,7 +627,7 @@
<para>The most known are <command>quilt</command>,
<emphasis>simple-patchsys</emphasis> (from the <emphasis>CDBS</emphasis>
package) and <command>dpatch</command>.
Please don't use any other patch system in Debian Med,
unless absolutely
necessary.</para>
- <sect3>
+ <sect3 id="quilt">
<title>Using <command>quilt</command></title>
<para>Using quilt is rather easy.</para>
<para>First, make sure you have correctly setup
quilt: open
@@ -639,7 +639,7 @@
QUILT_PATCHES="debian/patches"</programlisting>
</blockquote>
<para>After this, you're ready to start working
with quilt.</para>
- <sect4>
+ <sect4 id="quilt-create">
<title>Creating a patch</title>
<para>To create a patch, use the
<command>new</command> command.
Run:</para>
@@ -672,7 +672,7 @@
is currently applied (you can check
this with
<command>quilt
applied</command>).</para>
</sect4>
- <sect4>
+ <sect4 id="quilt-apply">
<title>Applying and unapplying
patches</title>
<para>Just two easy commands to do the
job:</para>
<itemizedlist>
@@ -687,7 +687,7 @@
<command>quilt
unapplied</command>.</para>
</tip>
</sect4>
- <sect4>
+ <sect4 id="quilt-edit">
<title>Editing patches</title>
<para>To edit a patch, first make it
the topmost:</para>
<blockquote>
@@ -702,7 +702,7 @@
you want to change, and, when you're
done, <command>quilt
refresh</command>.</para>
</sect4>
- <sect4>
+ <sect4 id="quilt-rename">
<title>Renaming patches</title>
<para>Sometimes it's useful to rename a
patch. Without
any hassle, do:</para>
@@ -713,12 +713,12 @@
</userinput></para>
</blockquote>
</sect4>
- <sect4>
+ <sect4 id="quilt-other">
<title>Other commands</title>
<para>Please see <command>man 1
quilt</command> to have a
comprehensive list of commands.</para>
</sect4>
- <sect4>
+ <sect4 id="quilt-integration">
<title>Integration in the build
process</title>
<para>Add in the very first part of
<filename>debian/rules</filename>
(i.e. before the targets), the
line:</para>
@@ -761,30 +761,30 @@
the simplest you can.</para>
</sect4>
</sect3>
- <sect3>
+ <sect3 id="dpatch">
<title>Using <command>dpatch</command></title>
- <sect4>
+ <sect4 id="dpatch-create-patch">
<title>Creating a patch</title>
<para>dpatch-edit-patch</para>
</sect4>
- <sect4>
+ <sect4 id="dpatch-apply-unapply">
<title>Applying and unapplying
patches</title>
<para>apply(-all), unapply(-all),
status</para>
</sect4>
- <sect4>
+ <sect4 id="dpatch-edit-patch">
<title>Editing patches</title>
<para>dpatch-edit-patch</para>
</sect4>
- <sect4>
+ <sect4 id="dpatch-rename-patch">
<title>Renaming patches</title>
<para>Is this possible?</para>
</sect4>
- <sect4>
+ <sect4 id="dpatch-other">
<title>Other commands</title>
<para>Please see <command>man 1
dpatch</command> for a
comprehensive list of commands.</para>
</sect4>
- <sect4>
+ <sect4 id="dpatch-integration">
<title>Integration in the build
process</title>
<para>Follow the instructions for quilt
and adapt the path of
inclusion to <filename
class="headerfile">/usr/share/dpatch/dpatch.make</filename></para>
_______________________________________________
debian-med-commit mailing list
[email protected]
http://lists.alioth.debian.org/mailman/listinfo/debian-med-commit
