[med-svn] r6306 - trunk/community/website/docs
Charles Plessy
plessy at alioth.debian.org
Sat Mar 19 08:53:51 UTC 2011
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:debian-med at lists.debian.org">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>
More information about the debian-med-commit
mailing list