| 1 |
plessy |
1847 |
<?xml version='1.0' encoding='UTF-8'?>
|
| 2 |
|
|
<?xml-stylesheet type="text/xsl"
|
| 3 |
|
|
href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"?>
|
| 4 |
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
| 5 |
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
| 6 |
|
|
<article xml:base="http://debian-med.alioth.debian.org/">
|
| 7 |
tille |
3777 |
<title>Debian Med Group Policy</title>
|
| 8 |
plessy |
1847 |
<articleinfo>
|
| 9 |
hanska-guest |
1277 |
<authorgroup>
|
| 10 |
|
|
<author>
|
| 11 |
plessy |
1847 |
<firstname>Andreas</firstname>
|
| 12 |
|
|
<surname>Tille</surname>
|
| 13 |
|
|
<contrib>First review </contrib>
|
| 14 |
hanska-guest |
1277 |
<email>tille@debian.org</email>
|
| 15 |
|
|
</author>
|
| 16 |
|
|
<author>
|
| 17 |
plessy |
1847 |
<firstname>David</firstname>
|
| 18 |
|
|
<surname>Paleino</surname>
|
| 19 |
|
|
<contrib>Initial writing </contrib>
|
| 20 |
hanska-guest |
1277 |
<email>d.paleino@gmail.com</email>
|
| 21 |
|
|
</author>
|
| 22 |
plessy |
1847 |
<author>
|
| 23 |
|
|
<firstname>Charles</firstname>
|
| 24 |
|
|
<surname>Plessy</surname>
|
| 25 |
plessy |
6354 |
<contrib>Contributions in 2008 and 2011</contrib>
|
| 26 |
plessy |
1847 |
<email>plessy@debian.org</email>
|
| 27 |
|
|
</author>
|
| 28 |
hanska-guest |
1277 |
</authorgroup>
|
| 29 |
|
|
<releaseinfo>
|
| 30 |
|
|
$ policy.xml rev. @REV@ - @DATE@ (@AUTHOR@) $
|
| 31 |
|
|
</releaseinfo>
|
| 32 |
plessy |
6354 |
<releaseinfo>
|
| 33 |
|
|
Source: svn://svn.debian.org/debian-med/trunk/community/website/docs/policy.xml
|
| 34 |
|
|
</releaseinfo>
|
| 35 |
plessy |
1847 |
</articleinfo>
|
| 36 |
hanska-guest |
1277 |
<mediaobject>
|
| 37 |
plessy |
1847 |
<objectinfo>
|
| 38 |
tille |
3777 |
<title>Debian Med Group</title>
|
| 39 |
plessy |
1847 |
</objectinfo>
|
| 40 |
hanska-guest |
1277 |
<imageobject>
|
| 41 |
|
|
<imagedata fileref="/img/debian-med.jpg" format="JPG" align="center" />
|
| 42 |
|
|
</imageobject>
|
| 43 |
|
|
</mediaobject>
|
| 44 |
plessy |
6306 |
<sect1 id="introduction">
|
| 45 |
hanska-guest |
1277 |
<title>Introduction</title>
|
| 46 |
tille |
3777 |
<para>Debian Med is a <quote><ulink url="http://blends.alioth.debian.org/blends">Debian Pure Blend</ulink></quote>
|
| 47 |
hanska-guest |
1277 |
with the aim to develop Debian into an operating system that is particularly
|
| 48 |
|
|
well fit for the requirements for medical practice and research.</para>
|
| 49 |
tille |
3777 |
<para>The Debian Med project presents packages that are associated
|
| 50 |
hanska-guest |
1277 |
with medicine, pre-clinical research, and life sciences. Its developments
|
| 51 |
|
|
are mostly focused on three areas for the moment: medical practice,
|
| 52 |
|
|
imaging and bioinformatics.</para>
|
| 53 |
|
|
<para>Over the previous years, several initiatives have spawned that
|
| 54 |
|
|
address the scientific disciplines like chemistry or bioinformatics.
|
| 55 |
tille |
3777 |
Debian Med is not a competition to these efforts but a platform to
|
| 56 |
|
|
present the packages to the community as a Debian Pure Blend.</para>
|
| 57 |
hanska-guest |
1277 |
</sect1>
|
| 58 |
plessy |
6306 |
<sect1 id="contribute">
|
| 59 |
hanska-guest |
1277 |
<title>How to Contribute</title>
|
| 60 |
|
|
<para>From the developer to the user, there is a long chain of tasks
|
| 61 |
|
|
in which we always welcome participation. First we must keep ourselves
|
| 62 |
|
|
informed about the software landscape in biology and medicine. Software
|
| 63 |
|
|
to be packaged is chosen according to criteria such as users' need and
|
| 64 |
|
|
the consistency of the distribution.</para>
|
| 65 |
|
|
<para>Once in Debian, the software is monitored for its quality and bugs
|
| 66 |
|
|
are fixed, if possible in collaboration with the upstream maintainer(s).
|
| 67 |
|
|
All this work would not be very useful if it remains confidential.</para>
|
| 68 |
|
|
<para>We also dedicate some time to advertise it to the world via
|
| 69 |
plessy |
1847 |
<ulink url="http://www.debian.org">www.debian.org</ulink>
|
| 70 |
hanska-guest |
1277 |
and to ease the integration of new members.</para>
|
| 71 |
plessy |
1847 |
<para>Please contact us on <ulink url="mailto:debian-med@lists.debian.org">debian-med@lists.debian.org</ulink>
|
| 72 |
hanska-guest |
1277 |
if you want to help to make medical and biological software available
|
| 73 |
plessy |
1847 |
to Debian users. Read the <link linkend="membership">Membership</link> section if you're
|
| 74 |
hanska-guest |
1277 |
interested in joining us.</para>
|
| 75 |
|
|
<para>If you speak a language other than English, you can contribute
|
| 76 |
|
|
rightaway with translations of package descriptions at
|
| 77 |
tille |
5212 |
<ulink url="http://ddtp.debian.net">ddtp.debian.net</ulink>.</para>
|
| 78 |
hanska-guest |
1277 |
<para>When working on these, you will find immediate targets for improvements
|
| 79 |
|
|
of the original English versions, too. For these, though, you need access
|
| 80 |
tille |
3777 |
to Debian Med's source code repository. Very welcome are tutorials that
|
| 81 |
hanska-guest |
1277 |
guide Debian users towards the use of packages to their immediate benefit.
|
| 82 |
|
|
You may also consider to write respective articles for Magazines, be they
|
| 83 |
|
|
online or in print.</para>
|
| 84 |
plessy |
6306 |
<sect2 id="membership">
|
| 85 |
|
|
<title>Membership</title>
|
| 86 |
hanska-guest |
1277 |
<para>To request membership to this group, please go on our
|
| 87 |
plessy |
1847 |
<ulink url="http://alioth.debian.org/projects/debian-med">Alioth page</ulink>,
|
| 88 |
|
|
or directly follow this <ulink url="http://alioth.debian.org/project/request.php?group_id=30063">link</ulink>.
|
| 89 |
hanska-guest |
1277 |
Remember that you must have an Alioth account before requesting
|
| 90 |
plessy |
1847 |
membership (see <ulink url="http://alioth.debian.org/account/register.php">here</ulink>
|
| 91 |
hanska-guest |
1277 |
to request an Alioth account).</para>
|
| 92 |
|
|
</sect2>
|
| 93 |
plessy |
6306 |
<sect2 id="readings">
|
| 94 |
|
|
<title>Essential readings</title>
|
| 95 |
plessy |
2408 |
<itemizedlist>
|
| 96 |
|
|
<listitem><para>The <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>: packages must conform to it.</para></listitem>
|
| 97 |
tille |
5212 |
<listitem><para>The <ulink url="http://www.debian.org/doc/developers-reference/">Developers Reference</ulink>: details best packaging practices.</para></listitem>
|
| 98 |
plessy |
2408 |
<listitem><para>The <ulink url="http://www.debian.org/doc/maint-guide/">New Maintainer's Guide</ulink>: puts a bit of the two above in practice.</para></listitem>
|
| 99 |
|
|
<listitem><para>The <ulink url="http://debian-med.alioth.debian.org/docs/policy.html">Debian Med Policy</ulink> (this document): explains how the work is organised in our team..</para></listitem>
|
| 100 |
|
|
</itemizedlist>
|
| 101 |
|
|
</sect2>
|
| 102 |
hanska-guest |
1277 |
</sect1>
|
| 103 |
plessy |
6306 |
<sect1 id="repositories">
|
| 104 |
plessy |
4307 |
<title>Repositories</title>
|
| 105 |
|
|
<para>We use Subversion (SVN) and Git repositories, hosted on
|
| 106 |
plessy |
1847 |
<ulink url="http://alioth.debian.org/">Alioth</ulink>, the hosting
|
| 107 |
hanska-guest |
1277 |
facility provided by Debian to free software developers. You can have a look at
|
| 108 |
plessy |
4307 |
each repository through Alioth's web interfaces: <ulink url="http://svn.debian.org/wsvn/debian-med/trunk/?rev=0&sc=0">wsvn</ulink>
|
| 109 |
|
|
<ulink url="http://svn.debian.org/viewsvn/debian-med">viewsvn</ulink> and
|
| 110 |
|
|
<ulink url="http://git.debian.org/">gitweb</ulink>.</para>
|
| 111 |
|
|
<para>The Subversion repository is the primary location for our source packages.
|
| 112 |
|
|
However, the Git repository is free to use for special cases, for instance when
|
| 113 |
|
|
the Subversion tags take a disproportionated size, when the maintainer is
|
| 114 |
|
|
much more comfortable with Git than Subversion, when some special features of
|
| 115 |
|
|
Git or git-buildpackage are desired, or more simply when the maintainer wants
|
| 116 |
plessy |
6376 |
to take the opportunity to familiarise with Git.
|
| 117 |
plessy |
4307 |
</para>
|
| 118 |
plessy |
6324 |
<warning id="umask">
|
| 119 |
|
|
<para>
|
| 120 |
plessy |
6376 |
For most direct operations on the repositories in Alioth, an <command>umask</command> of <literal>002</literal> is necessary to avoid problems of missing write permission to the other team members.
|
| 121 |
plessy |
6324 |
</para>
|
| 122 |
|
|
</warning>
|
| 123 |
plessy |
6306 |
<sect2 id="source">
|
| 124 |
hanska-guest |
1277 |
<title>Give me the source!</title>
|
| 125 |
|
|
<para>
|
| 126 |
plessy |
6376 |
To check sources out from our repositories, please do:
|
| 127 |
hanska-guest |
1277 |
<itemizedlist>
|
| 128 |
|
|
<listitem>
|
| 129 |
plessy |
6348 |
<para>
|
| 130 |
|
|
If you are a member of Debian Med or a Debian developer, you have
|
| 131 |
|
|
write permission:<programlisting>
|
| 132 |
|
|
<command>svn co</command> <filename class="directory">svn+ssh://user@alioth.debian.org/svn/debian-med/trunk/...</filename>
|
| 133 |
|
|
<command>git clone</command> <filename class="directory">git+ssh://user@alioth.debian.org/git/debian-med/<package>.git</filename></programlisting>
|
| 134 |
|
|
</para>
|
| 135 |
hanska-guest |
1277 |
</listitem>
|
| 136 |
|
|
<listitem>
|
| 137 |
plessy |
6348 |
<para>
|
| 138 |
|
|
For read-only access, the syntax is slightly
|
| 139 |
|
|
different:<programlisting>
|
| 140 |
|
|
<command>svn co</command> <filename class="directory">svn://svn.debian.org/svn/debian-med/trunk/...</filename>
|
| 141 |
|
|
<command>git clone</command> <filename class="directory">git://git.debian.org/git/debian-med/<package>.git</filename></programlisting>
|
| 142 |
|
|
</para>
|
| 143 |
hanska-guest |
1277 |
</listitem>
|
| 144 |
|
|
</itemizedlist>
|
| 145 |
|
|
</para>
|
| 146 |
plessy |
1847 |
<para>
|
| 147 |
|
|
Another way to check the sources is through the use of the
|
| 148 |
|
|
<command>debcheckout</command> command, from the
|
| 149 |
|
|
<ulink url="http://packages.debian.org/devscripts">devscripts</ulink>
|
| 150 |
plessy |
6349 |
package. Its <option>-a</option> option checks out or clone for write
|
| 151 |
|
|
access.
|
| 152 |
plessy |
1847 |
</para>
|
| 153 |
hanska-guest |
1277 |
</sect2>
|
| 154 |
plessy |
6347 |
<sect2 id="ssh-tips">
|
| 155 |
|
|
<title>SSH tips</title>
|
| 156 |
|
|
<para id="ssh-config">
|
| 157 |
|
|
You can avoid specifying your Alioth user name by setting it in
|
| 158 |
|
|
<filename>~/.ssh/config</filename>:<programlisting>
|
| 159 |
|
|
Host *.debian.org
|
| 160 |
|
|
User your-user-name</programlisting>
|
| 161 |
|
|
</para>
|
| 162 |
|
|
<para id="ssh-add">
|
| 163 |
|
|
You can avoid typing your SSH password again and again using the
|
| 164 |
|
|
<code><command>ssh-add</command></code> command. On remote connections
|
| 165 |
|
|
the SSH agent needs to be enabled with the command
|
| 166 |
|
|
<code><command>eval</command>
|
| 167 |
|
|
<option>$(</option><command>ssh-agent</command><option>)</option></code>.
|
| 168 |
|
|
</para>
|
| 169 |
tille |
6351 |
<para id="wiki-alioth">
|
| 170 |
|
|
In case of trouble getting SSH working it is a good idea to read
|
| 171 |
|
|
<ulink url="http://wiki.debian.org/Alioth/SSH">this wiki article</ulink>.
|
| 172 |
tille |
6352 |
</para>
|
| 173 |
plessy |
6347 |
</sect2>
|
| 174 |
plessy |
6327 |
<sect2 id="svn-repository-structure">
|
| 175 |
|
|
<title>Subversion repository structure</title>
|
| 176 |
plessy |
6350 |
<para>The SVN repository is structured as follows:<programlisting>
|
| 177 |
plessy |
1847 |
debian-med/
|
| 178 |
|
|
└ trunk/
|
| 179 |
|
|
├ community/
|
| 180 |
|
|
│ ├ debtags/
|
| 181 |
|
|
│ ├ infrastructure/
|
| 182 |
|
|
│ └ website/
|
| 183 |
|
|
└ packages/
|
| 184 |
|
|
├ <package A>/
|
| 185 |
|
|
│ ├ branches/
|
| 186 |
|
|
│ ├ tags/
|
| 187 |
|
|
│ └ trunk/
|
| 188 |
|
|
│ └ debian/
|
| 189 |
|
|
├ <package B>/
|
| 190 |
|
|
│ ├ branches/
|
| 191 |
|
|
│ ├ tags/
|
| 192 |
|
|
│ └ trunk/
|
| 193 |
|
|
│ └ debian/
|
| 194 |
plessy |
6350 |
…</programlisting>
|
| 195 |
plessy |
1847 |
</para>
|
| 196 |
|
|
<note><para>We are currently considering an alternative layout in which all
|
| 197 |
|
|
the <filename>trunk</filename>, <filename>tags</filename> and
|
| 198 |
tille |
5212 |
<filename>branches</filename> directories are grouped together, so that developers can checkout trunks without tags.</para></note>
|
| 199 |
hanska-guest |
1277 |
</sect2>
|
| 200 |
plessy |
6331 |
<sect2 id="subversion-tips">
|
| 201 |
|
|
<title>Subversion tips</title>
|
| 202 |
plessy |
6339 |
<para id="svn-buildpackage-aliases">
|
| 203 |
plessy |
6331 |
Suggested aliases for
|
| 204 |
|
|
<command>svn-buildpackage</command>:<programlisting>
|
| 205 |
|
|
alias <command>svn-b</command>='svn-buildpackage -us -uc -rfakeroot --svn-ignore'
|
| 206 |
|
|
alias <command>svn-br</command>='svn-b --svn-dont-purge --svn-reuse'
|
| 207 |
|
|
alias <command>svn-bt</command>='svn-buildpackage --svn-tag -rfakeroot'</programlisting>
|
| 208 |
|
|
</para>
|
| 209 |
plessy |
6345 |
<para id="svn-mergewithupstream">
|
| 210 |
|
|
<command>svn-inject</command> sets up correctly the
|
| 211 |
|
|
<literal>mergeWithUpstream</literal> property for the SVN directories
|
| 212 |
|
|
where packages are stored. In case <command>svn-inject</command> was
|
| 213 |
|
|
not used, you can do it by hand with the command
|
| 214 |
|
|
<code><command>svn propset</command>
|
| 215 |
|
|
<replaceable>mergeWithUpstream</replaceable>
|
| 216 |
|
|
<replaceable>1</replaceable> <replaceable>debian</replaceable></code>.
|
| 217 |
|
|
</para>
|
| 218 |
plessy |
6339 |
<para id="download-upstream-source">
|
| 219 |
plessy |
6331 |
To download the upstream sources (if there is a
|
| 220 |
|
|
<filename>debian/watch</filename> file): <code><command>echo
|
| 221 |
|
|
"origDir=.." >> .svn/deb-layout && uscan
|
| 222 |
|
|
--force-download</command></code>. Alternatively, you can try
|
| 223 |
|
|
<code><command>debian/rules get-orig-source</command></code>.
|
| 224 |
|
|
</para>
|
| 225 |
plessy |
6339 |
<para id="svn-write-access">
|
| 226 |
plessy |
6331 |
If you're a Debian developer or a member of the Debian Med group on
|
| 227 |
|
|
Alioth, you can commit your changes: <command>svn commit</command> (also
|
| 228 |
|
|
<command>svn ci</command>). Otherwise, you can ask to be added to the
|
| 229 |
|
|
group (see the <link linkend="membership">Membership</link> section), or
|
| 230 |
|
|
send the result of <command>svn diff</command> to the <ulink
|
| 231 |
|
|
url="mailto:debian-med@lists.debian.org">mailing list</ulink>
|
| 232 |
|
|
(<command>gzip -9</command> it, if it's too large).
|
| 233 |
|
|
</para>
|
| 234 |
plessy |
6339 |
<para id="svn-tag-release">
|
| 235 |
plessy |
6335 |
It may happen that a package version has been uploaded to Debian
|
| 236 |
|
|
repositories, and you forgot to tag the last build with
|
| 237 |
|
|
<command>svn-buildpackage --svn-tag</command>. You can tag this package
|
| 238 |
|
|
also retroactively. A first step, creating
|
| 239 |
|
|
the tags directory, can be achieved in two ways: either create it
|
| 240 |
|
|
locally as sibling of <filename class="directory">trunk/</filename> with
|
| 241 |
|
|
<code><command>svn mkdir</command> <filename class="directory">tags</filename></code>, and commit with
|
| 242 |
|
|
<code><command>svn commit</command></code>, or create it remotely with
|
| 243 |
|
|
<code><command>svn mkdir</command> <filename class="directory">svn+ssh://user@svn.debian.org/svn/debian-med/trunk/packages/<package>/tags</filename></code>.
|
| 244 |
|
|
After the tags directory has been created, you're ready to tag the
|
| 245 |
|
|
package: <code><command>svn-buildpackage</command> <option>--svn-tag-only</option> <option>--svn-no-autodch</option></code>.
|
| 246 |
|
|
The <option>--svn-no-autodch</option> avoids
|
| 247 |
|
|
<filename>debian/changelog</filename> to be marked as <literal>UNRELEASED</literal>.
|
| 248 |
|
|
</para>
|
| 249 |
plessy |
6344 |
<para id="example-svn-session">
|
| 250 |
|
|
Here is an example session where a package is prepared manually:<programlisting>
|
| 251 |
|
|
# Check out debian-med/trunk, cd to debian-med/trunk/packages
|
| 252 |
|
|
# Create new project folder with
|
| 253 |
|
|
svn mkdir projectname
|
| 254 |
|
|
svn mkdir projectname/trunk
|
| 255 |
|
|
|
| 256 |
|
|
# Put orig.tar.gz in place
|
| 257 |
|
|
mv some_version.orig.tar.gz projectname
|
| 258 |
|
|
|
| 259 |
|
|
# Inform svn-buildpackage about the location of the orig.tar.gz
|
| 260 |
|
|
echo "origDir=.." > projectname/trunk/.svn/deb-layout
|
| 261 |
|
|
|
| 262 |
|
|
# Untar source tree for development
|
| 263 |
|
|
cd projectname
|
| 264 |
|
|
tar xzvf some_version.orig.tar.gz
|
| 265 |
|
|
cd some-version # entering the unpackaged source tree
|
| 266 |
|
|
if [ ! -d debian ]; then dh_make ; fi
|
| 267 |
|
|
mv debian ../trunk
|
| 268 |
|
|
ln -s ../trunk/debian .
|
| 269 |
|
|
|
| 270 |
|
|
# continue development
|
| 271 |
|
|
fakeroot ./debian/rules binary
|
| 272 |
|
|
|
| 273 |
|
|
# until it works, finally
|
| 274 |
|
|
cd ..
|
| 275 |
|
|
|
| 276 |
|
|
# debian directory is the only thing that is stored in svn, to be merged with upstream
|
| 277 |
|
|
svn propset mergeWithUpstream 1 trunk/debian
|
| 278 |
|
|
|
| 279 |
|
|
# See if things can be compiled via svn-buildpackage
|
| 280 |
|
|
cd trunk
|
| 281 |
|
|
svn-buildpackage -rfakeroot -uc -us
|
| 282 |
|
|
|
| 283 |
|
|
# check build
|
| 284 |
|
|
lintian ../build-area/*changes</programlisting>
|
| 285 |
|
|
</para>
|
| 286 |
plessy |
6331 |
</sect2>
|
| 287 |
plessy |
6327 |
<sect2 id="git-repository-structures">
|
| 288 |
|
|
<title>Common Git repository structures</title>
|
| 289 |
|
|
<para>
|
| 290 |
|
|
The area on Alioth that contains the Git repositories (<filename
|
| 291 |
|
|
class="directory">/git/debian-med</filename>) is not itself structured,
|
| 292 |
|
|
but the repositories can be arranged in different possible layouts.
|
| 293 |
|
|
</para>
|
| 294 |
|
|
<sect3 id="git-buildpackage">
|
| 295 |
|
|
<title><command>git-buildpackage</command></title>
|
| 296 |
|
|
<para>
|
| 297 |
|
|
Most of our packages using Git and stored in Alioth are managed with
|
| 298 |
|
|
the <command>git-buildpackage</command> helper. The
|
| 299 |
|
|
<literal>master</literal> branch contains the full source package.
|
| 300 |
|
|
The <literal>upstream</literal> branch contains the upstream source,
|
| 301 |
|
|
after repacking when necessary (non-free files, large convenience code
|
| 302 |
|
|
copies, …). The <literal>pristine-tar</literal> contains the data
|
| 303 |
|
|
necessary to recreate an original tarball from the repository with a
|
| 304 |
|
|
reproducible checksum.
|
| 305 |
|
|
</para>
|
| 306 |
|
|
<para>
|
| 307 |
|
|
Debian releases are tagged with names like
|
| 308 |
plessy |
6376 |
<literal>debian/debianversion</literal> and upstream releases are
|
| 309 |
plessy |
6327 |
tagged with names like <literal>upstream/upstreamversion</literal>.
|
| 310 |
|
|
</para>
|
| 311 |
|
|
</sect3>
|
| 312 |
|
|
<sect3 id="git-without-tarball">
|
| 313 |
|
|
<title>Social Git</title>
|
| 314 |
|
|
<para>
|
| 315 |
|
|
For some projects, like the ones hosted on <ulink
|
| 316 |
plessy |
6376 |
url="http://www.github.com">GitHub</ulink> or <ulink
|
| 317 |
plessy |
6327 |
url="http://www.gitorious.com">Gitorious</ulink>, it may be easier to
|
| 318 |
|
|
forward changes made in the Debian package if this one is itself
|
| 319 |
|
|
hosted on the same platform, as a clone. In that case, the layouts
|
| 320 |
|
|
may vary from package to packages. However, there are good chances
|
| 321 |
|
|
that the branch that contains the Debian source package is called
|
| 322 |
|
|
<literal>debian</literal>.
|
| 323 |
|
|
</para>
|
| 324 |
|
|
</sect3>
|
| 325 |
|
|
</sect2>
|
| 326 |
plessy |
6321 |
|
| 327 |
|
|
<sect2 id="git-tips">
|
| 328 |
|
|
<title>Git tips</title>
|
| 329 |
plessy |
6325 |
<para id="new-repository-with-gbp">
|
| 330 |
|
|
Example to create a new git repository for a package where the upstream
|
| 331 |
|
|
sources are distributed as file archives (tar, zip, …):<programlisting>
|
| 332 |
|
|
<command>mkdir</command> <filename class="directory">package</filename>
|
| 333 |
|
|
<command>cd</command> <filename class="directory">package</filename>
|
| 334 |
|
|
<command>git init</command>
|
| 335 |
|
|
<command>git import-orig</command> <option>--pristine-tar</option> <filename>/path/to/package_version.orig.tar.gz</filename>
|
| 336 |
|
|
<command>dh_make</command> <option>-p package_x.y.z</option></programlisting>
|
| 337 |
|
|
The above steps will create a repository with the appropriate layout for
|
| 338 |
|
|
<command>git-buildpackage</command>, with three branches:
|
| 339 |
|
|
<literal>master</literal> (where the Debian development will happen),
|
| 340 |
|
|
<literal>pristine-tar</literal> used by the
|
| 341 |
|
|
<literal>pristine-tar</literal> tool during the package build process to
|
| 342 |
|
|
recreate the original tarball, and <literal>upstream</literal>, which
|
| 343 |
|
|
will contain the upstream source.
|
| 344 |
plessy |
6321 |
</para>
|
| 345 |
plessy |
6325 |
<para id="debcheckout-sets-git-options">
|
| 346 |
|
|
To display your name and more nicely in the Git log, you should instruct
|
| 347 |
|
|
Git to do so (the <option>--global</option> option is to say Git these
|
| 348 |
|
|
are the default parameters for every Git repository you commit to,
|
| 349 |
|
|
without it the settings will be per-repository only):<programlisting>
|
| 350 |
|
|
<command>git config</command> <option><optional>--global</optional></option> <option>user.name "$DEBFULLNAME"</option>
|
| 351 |
|
|
<command>git config</command> <option><optional>--global</optional></option> <option>user.email "$DEBEMAIL"</option></programlisting>
|
| 352 |
|
|
</para>
|
| 353 |
|
|
<para id="debcheckout-git-track">
|
| 354 |
|
|
To clone and follow every branch of a git repository containing a
|
| 355 |
|
|
package that is already in the Debian archive, you can use the
|
| 356 |
|
|
<command>debcheckout</command> command with its
|
| 357 |
|
|
<command><option>--git-track='*'</option></command> option. To restrict
|
| 358 |
|
|
the tracked branch to the standard ones used by
|
| 359 |
|
|
<command>git-buildpackage</command>, <literal>master upstream
|
| 360 |
|
|
pristine-tar</literal> can be passed instead of the wildcard.
|
| 361 |
|
|
</para>
|
| 362 |
|
|
<para id="git-track-new-branches">
|
| 363 |
plessy |
6322 |
Example commands to track new branches: <programlisting>
|
| 364 |
plessy |
6325 |
<command>git branch</command> <option>-t <replaceable>upstream</replaceable> <replaceable>origin/upstream</replaceable></option>
|
| 365 |
|
|
<command>git branch</command> <option>-t <replaceable>pristine-tar</replaceable> <replaceable>origin/pristine-tar</replaceable></option></programlisting>
|
| 366 |
plessy |
6322 |
</para>
|
| 367 |
plessy |
6325 |
<para id="git-options-devscripts">
|
| 368 |
|
|
If the <package>devscripts</package> variables
|
| 369 |
|
|
<varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname> are set,
|
| 370 |
|
|
<command>debcheckout</command> will set <command>git</command>'s options
|
| 371 |
|
|
<varname>user.email</varname> and <varname>user.name</varname>
|
| 372 |
|
|
accordingly.
|
| 373 |
plessy |
6321 |
</para>
|
| 374 |
plessy |
6325 |
<para id="git-add-alioth-branch">
|
| 375 |
|
|
To push changes to Alioth, a remote branch needs to be configured. This
|
| 376 |
|
|
is done automatically after cloning a repository, for instance with
|
| 377 |
|
|
<link linkend="debcheckout-git-track">debcheckout</link>. The default
|
| 378 |
|
|
remote branch is called <quote>origin</quote>. Here are example
|
| 379 |
|
|
commands to set up Alioth as a remote branch on a freshly created
|
| 380 |
|
|
repository:<programlisting>
|
| 381 |
|
|
<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://alioth.debian.org/git/debian-med/package.git</filename></programlisting>
|
| 382 |
|
|
</para>
|
| 383 |
|
|
<para id="create-git-repository-on-alioth">
|
| 384 |
|
|
There is a small script called <command>setup-repository</command> in
|
| 385 |
|
|
the <filename class="directory">/git/debian-med</filename> directory on
|
| 386 |
|
|
Alioth. <code><command>./setup-repository</command>
|
| 387 |
|
|
<option>packagename</option> <option>"Description of the
|
| 388 |
|
|
package"</option></code> will create a <filename
|
| 389 |
|
|
class="directory">packagename.git</filename> repository on with the
|
| 390 |
|
|
proper hooks set up for our team.
|
| 391 |
|
|
</para>
|
| 392 |
|
|
<para id="push-package-to-alioth">
|
| 393 |
|
|
To push the package (make sure you've added the alioth remote!), do the
|
| 394 |
|
|
following:<code><command>git push</command> <option>origin
|
| 395 |
|
|
master</option></code>. For the first push, it's necessary to specify
|
| 396 |
|
|
<option>origin master</option>. The next time you will push, a
|
| 397 |
|
|
<command>git push</command> will suffice.
|
| 398 |
|
|
</para>
|
| 399 |
|
|
<para id="git-push-all-tags">
|
| 400 |
|
|
<command>git push</command>this will only push the
|
| 401 |
|
|
<literal>master</literal> branch unless it is somehow related to other
|
| 402 |
|
|
branches), so be sure to also do a run with <option>--all</option>, and one with <option>--tags</option> if you created new tags.
|
| 403 |
|
|
</para>
|
| 404 |
plessy |
6339 |
<para id="git-tag-release">
|
| 405 |
|
|
To tag a release:
|
| 406 |
|
|
<code><command>git tag</command> <option>debian/x.y-z</option></code>.
|
| 407 |
|
|
You can also easily retroactively make tags:
|
| 408 |
|
|
<code><command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option></code>.
|
| 409 |
|
|
Remember to <code><command>git push --tags</command></code>.
|
| 410 |
|
|
</para>
|
| 411 |
plessy |
6326 |
<para id="git-layout-variants">
|
| 412 |
|
|
In particular for Git repositories that are not stored in Alioth, the
|
| 413 |
|
|
layout can differ from <command>git-buildpackage</command> conventions.
|
| 414 |
|
|
In that case, look for instance for a branch called <literal>debian</literal>.
|
| 415 |
|
|
</para>
|
| 416 |
plessy |
6339 |
<para id="git-debian-version-from-commit">
|
| 417 |
plessy |
6329 |
If upstream manages his sources with Git, the following makefile
|
| 418 |
plessy |
6328 |
script can help producing a version number when no Git tag is
|
| 419 |
|
|
available:<programlisting>
|
| 420 |
|
|
SOURCEPKG=$(shell dpkg-parsechangelog | sed -n 's/^Source: \(.*\)/\1/p')
|
| 421 |
|
|
UPSTREAM=$(shell dpkg-parsechangelog | sed -n 's/^Version: \(.*\)-[^-]*/\1/p')
|
| 422 |
|
|
SHA1=$(lastword $(subst ~g, ,$(UPSTREAM)))
|
| 423 |
|
|
ORIG=${SOURCEPKG}_${UPSTREAM}.orig.tar.gz
|
| 424 |
|
|
|
| 425 |
|
|
describe-current-version:
|
| 426 |
|
|
git describe --tags upstream | sed 's,^release-,,;s,-,+,;s,-,~,;'
|
| 427 |
|
|
|
| 428 |
|
|
get-orig-source:
|
| 429 |
|
|
git archive --format=tar $(SHA1) | gzip -9 > ../$(ORIG)</programlisting>
|
| 430 |
plessy |
6339 |
</para>
|
| 431 |
|
|
<para>
|
| 432 |
|
|
To make <command>git-buildpackage</command> builds the package with a
|
| 433 |
plessy |
6376 |
chroot, you can add the following to the configuration file <filename>~/.gbp.conf</filename> or <filename>debian/gbp.conf</filename>:<programlisting>
|
| 434 |
plessy |
6339 |
[DEFAULT]
|
| 435 |
|
|
builder = ~/bin/git-pbuilder
|
| 436 |
|
|
cleaner = fakeroot debian/rules clean
|
| 437 |
|
|
pristine-tar = True
|
| 438 |
|
|
|
| 439 |
|
|
[git-buildpackage]
|
| 440 |
|
|
# use this for more svn-buildpackage like behaviour:
|
| 441 |
|
|
export-dir = ../build-area/
|
| 442 |
|
|
tarball-dir = ../tarballs/</programlisting>
|
| 443 |
|
|
With this configuration file you're specifying that
|
| 444 |
|
|
<command>git-buildpackage</command> will use
|
| 445 |
|
|
<filename>~/bin/git-pbuilder</filename> as the builder script. This is
|
| 446 |
|
|
an example script you can use:<programlisting>
|
| 447 |
|
|
#!/bin/sh
|
| 448 |
|
|
set -e
|
| 449 |
|
|
|
| 450 |
|
|
pdebuild --pbuilder cowbuilder --debbuildopts "-i\.git -I.git $*"
|
| 451 |
|
|
rm ../*_source.changes</programlisting>
|
| 452 |
|
|
This will build the package inside the default cowbuilder chroot, while
|
| 453 |
|
|
passing any more parameters directly do <command>dpkg-buildpackage</command>.
|
| 454 |
|
|
</para>
|
| 455 |
plessy |
6321 |
</sect2>
|
| 456 |
|
|
|
| 457 |
plessy |
6306 |
<sect2 id="subversion-to-git">
|
| 458 |
plessy |
4307 |
<title>Migration of a source package from Subversion to Git.</title>
|
| 459 |
|
|
<para>There is no easy way to prepare a Git repository from our Subversion repository that would
|
| 460 |
|
|
look like the package was always managed in Git, because we use svn-buildpackage with the
|
| 461 |
|
|
mergeWithUpstream property set, which excludes the upstream sources. Nevertheless, the
|
| 462 |
plessy |
6376 |
following recipe will generate a Git repository that contains all the history of
|
| 463 |
plessy |
4307 |
the debian directory, plus a collection of selected upstream source releases.
|
| 464 |
|
|
</para>
|
| 465 |
|
|
<itemizedlist>
|
| 466 |
|
|
<listitem>
|
| 467 |
|
|
<para>Start the conversion as explained in the <ulink url="http://wiki.debian.org/Alioth/Git#ConvertaSVNAliothrepositorytoGit">Alioth/Git</ulink> page of the Debian wiki. To be consistent with a later usage of <command>git-buildpackage</command>, it is preferable to prefix the tag names <quote>debian</quote>. During this conversion, you can take advantage of the file <filename>/trunk/community/infrastructure/comitters</filename> in the Subversion repository, and expand it if necessary.</para>
|
| 468 |
|
|
</listitem>
|
| 469 |
|
|
<listitem>
|
| 470 |
|
|
<para>Import of the upstream original tarballs that you find relevant, for instance the ones that were part of a stable release). When this paragraph was written, it was necessary to follow special instruction detailed in <ulink url="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=471560">bug 471560</ulink>.
|
| 471 |
|
|
</para>
|
| 472 |
|
|
</listitem>
|
| 473 |
|
|
<listitem>
|
| 474 |
|
|
<para>Upload to alioth.debian.org/git/debian-med and set up the hooks and other meta-data as explained in the <ulink url="http://wiki.debian.org/Alioth/Git">Alioth/Git</ulink> page of the Debian wiki.
|
| 475 |
|
|
</para>
|
| 476 |
|
|
</listitem>
|
| 477 |
|
|
</itemizedlist>
|
| 478 |
plessy |
5517 |
<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>
|
| 479 |
plessy |
4307 |
</sect2>
|
| 480 |
plessy |
6306 |
<sect2 id="updating-git-package">
|
| 481 |
plessy |
5518 |
<title>Updating a source package managed with Git</title>
|
| 482 |
|
|
<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>
|
| 483 |
plessy |
6376 |
<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 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 git-buildpackage, it is often unnecessary to rename the freshly downloaded original upstream archive.</para>
|
| 484 |
plessy |
5518 |
</sect2>
|
| 485 |
hanska-guest |
1277 |
</sect1>
|
| 486 |
plessy |
6306 |
<sect1 id="packaging">
|
| 487 |
hanska-guest |
1277 |
<title>Packaging</title>
|
| 488 |
plessy |
6306 |
<sect2 id="itp">
|
| 489 |
hanska-guest |
1277 |
<title>Announcing intent to package</title>
|
| 490 |
|
|
<para>If you intent to work on a Debian package you should follow
|
| 491 |
plessy |
1847 |
the <ulink url="http://www.debian.org/devel/wnpp/#l1">normal Debian rules</ulink> and file a <acronym>WNPP</acronym> bug report.</para>
|
| 492 |
tille |
3777 |
<para>It is a good idea to keep the Debian Med mailing list
|
| 493 |
plessy |
1847 |
<ulink url="mailto:debian-med@lists.debian.org">debian-med@lists.debian.org</ulink>
|
| 494 |
plessy |
2630 |
<ulink url="http://www.debian.org/Bugs/Reporting#xcc"> in CC</ulink> and to set it
|
| 495 |
|
|
as the owner of the ITP to keep your co-workers informed. This will ensure that we notice
|
| 496 |
plessy |
4042 |
if for some reason the package has not been uploaded.</para>
|
| 497 |
|
|
<para>In addition, please add the package to the <quote>task</quote> file where it fits
|
| 498 |
|
|
the best, and document your ITP number using the <command>WNPP</command> field name.</para>
|
| 499 |
hanska-guest |
1277 |
</sect2>
|
| 500 |
plessy |
1847 |
</sect1>
|
| 501 |
plessy |
6306 |
<sect1 id="tasks">
|
| 502 |
plessy |
4042 |
<title>Tasks</title>
|
| 503 |
|
|
<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>
|
| 504 |
|
|
<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>
|
| 505 |
|
|
<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>
|
| 506 |
|
|
</sect1>
|
| 507 |
plessy |
6306 |
<sect1 id="policy">
|
| 508 |
plessy |
1847 |
<title>Policy</title>
|
| 509 |
plessy |
6306 |
<sect2 id="debian-control">
|
| 510 |
plessy |
1847 |
<title><filename>debian/control</filename></title>
|
| 511 |
|
|
<orderedlist>
|
| 512 |
|
|
<listitem>
|
| 513 |
|
|
<formalpara>
|
| 514 |
|
|
<title>Section</title>
|
| 515 |
|
|
<para>Should be <quote>science</quote> for the source package.</para>
|
| 516 |
|
|
</formalpara>
|
| 517 |
|
|
</listitem>
|
| 518 |
|
|
|
| 519 |
|
|
<listitem>
|
| 520 |
|
|
<formalpara>
|
| 521 |
|
|
<title>Priority</title>
|
| 522 |
|
|
<para>Should be <quote>optional</quote> unless forbidden by the Debian policy (see section 2.5). Packages of priority <quote>extra</quote> are excluded from some QA tests.</para>
|
| 523 |
|
|
</formalpara>
|
| 524 |
|
|
</listitem>
|
| 525 |
|
|
|
| 526 |
|
|
<listitem>
|
| 527 |
|
|
<formalpara>
|
| 528 |
|
|
<title>Maintainer</title>
|
| 529 |
tille |
3777 |
<para>Maintainer should be Debian Med Packaging Team <email>debian-med-packaging@lists.alioth.debian.org</email>. Please subscribe to this list if you list yourself in the <code>Uploaders:</code> field of one of Debian Med's packages. You can refer to the <ulink url="http://qa.debian.org/developer.php?login=debian-med-packaging@lists.alioth.debian.org">QA page</ulink> corresponding to this email to gather information about the packages.</para>
|
| 530 |
plessy |
1847 |
</formalpara>
|
| 531 |
|
|
</listitem>
|
| 532 |
|
|
|
| 533 |
|
|
<listitem>
|
| 534 |
|
|
<formalpara>
|
| 535 |
|
|
<title>Upload by Debian Maintainers</title>
|
| 536 |
|
|
<para>Should be enabled with the field <code>DM-Upload-Allowed: yes</code>. This means that when an Uploader becomes Debian Maintainer, he will immediately get the possibility to upload the package to Debian. Please consider this when you sponsor packages in which some Uploaders are added.</para>
|
| 537 |
|
|
</formalpara>
|
| 538 |
|
|
</listitem>
|
| 539 |
|
|
|
| 540 |
|
|
<listitem>
|
| 541 |
|
|
<formalpara>
|
| 542 |
|
|
<title>Uploaders</title>
|
| 543 |
plessy |
6376 |
<para>Please add yourself as an uploader when you have a significant interest in a package. Being Uploader means that you are expected to answer to the bug reports. For more occasional works, you can do a <ulink url="http://www.debian.org/doc/developers-reference/pkgs#nmu-team-upload">team upload</ulink>.
|
| 544 |
plessy |
1847 |
</para>
|
| 545 |
|
|
</formalpara>
|
| 546 |
|
|
</listitem>
|
| 547 |
|
|
|
| 548 |
|
|
<listitem>
|
| 549 |
|
|
<formalpara>
|
| 550 |
|
|
<title>Standards-Version</title>
|
| 551 |
|
|
<para>Please always use the latest unless there are concerns for backporting. If no changes are needed, please indicate this fact in the changelog, and increment the value of the field.</para>
|
| 552 |
|
|
</formalpara>
|
| 553 |
|
|
</listitem>
|
| 554 |
|
|
|
| 555 |
|
|
<listitem>
|
| 556 |
|
|
<formalpara>
|
| 557 |
|
|
<title>Homepage</title>
|
| 558 |
|
|
<para>should be documented whenever possible</para>
|
| 559 |
|
|
</formalpara>
|
| 560 |
|
|
</listitem>
|
| 561 |
|
|
|
| 562 |
|
|
<listitem>
|
| 563 |
|
|
<formalpara>
|
| 564 |
|
|
<title>Vcs-Svn: and Vcs-Browser:</title>
|
| 565 |
plessy |
4307 |
<para>Please use the following templates:
|
| 566 |
plessy |
1847 |
<programlisting>
|
| 567 |
hanska-guest |
1277 |
Vcs-Svn: svn://svn.debian.org/svn/debian-med/trunk/packages/<package>/trunk/
|
| 568 |
|
|
Vcs-Browser: http://svn.debian.org/wsvn/debian-med/trunk/packages/<package>/trunk/?rev=0&sc=0
|
| 569 |
plessy |
4307 |
</programlisting>or
|
| 570 |
|
|
<programlisting>
|
| 571 |
|
|
Vcs-Git: git://git.debian.org/git/debian-med/<package>.git
|
| 572 |
|
|
Vcs-Browser: http://git.debian.org/?p=debian-med/<package>.git
|
| 573 |
plessy |
1847 |
</programlisting>
|
| 574 |
plessy |
4304 |
</para>
|
| 575 |
plessy |
1847 |
</formalpara>
|
| 576 |
|
|
</listitem>
|
| 577 |
|
|
</orderedlist>
|
| 578 |
hanska-guest |
1277 |
</sect2>
|
| 579 |
plessy |
1847 |
|
| 580 |
plessy |
6306 |
<sect2 id="debian-copyright">
|
| 581 |
plessy |
1847 |
<title><filename>debian/copyright</filename></title>
|
| 582 |
tille |
6399 |
<para>We use the <ulink url="http://wiki.debian.org/Proposals/CopyrightFormat">proposed machine-readable format</ulink>
|
| 583 |
|
|
for the <filename>debian/copyright</filename> file. The <computeroutput>Source</computeroutput> field does not
|
| 584 |
|
|
need to contain the full URL to the particular version that is being packaged, since this can be determined by
|
| 585 |
|
|
the <command>uscan</command> program with the <filename>debian/watch</filename> file. Please list yourself in the
|
| 586 |
|
|
<computeroutput>Files: debian/*</computeroutput> section if you think that your contributions are not trivial and
|
| 587 |
|
|
therefore subjected to copyright. Please chose a license that is compatible with the program you package. You can
|
| 588 |
|
|
also use <quote>same as if it were in the public domain</quote> or <quote>same as the packaged program itself</quote>.
|
| 589 |
|
|
</para>
|
| 590 |
|
|
<para>To verify the correct syntax of the <filename>debian/copyright</filename> file you can use</para>
|
| 591 |
|
|
<blockquote><userinput>
|
| 592 |
|
|
<command>config-edit -application dpkg-copyright -ui none</command>
|
| 593 |
|
|
</userinput></blockquote>
|
| 594 |
plessy |
1847 |
</sect2>
|
| 595 |
|
|
|
| 596 |
plessy |
6306 |
<sect2 id="debian-changelog">
|
| 597 |
plessy |
1847 |
<title><filename>debian/changelog</filename></title>
|
| 598 |
|
|
<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>
|
| 599 |
|
|
</sect2>
|
| 600 |
plessy |
6306 |
<sect2 id="debian-readme-source">
|
| 601 |
plessy |
2667 |
<title><filename>debian/README.source</filename></title>
|
| 602 |
plessy |
6376 |
<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 archive, when we repack the sources,…</para>
|
| 603 |
plessy |
2667 |
</sect2>
|
| 604 |
plessy |
1847 |
|
| 605 |
plessy |
6306 |
<sect2 id="debhelper">
|
| 606 |
plessy |
1847 |
<title>Debhelper</title>
|
| 607 |
tille |
6311 |
<para>Debhelper uses compatibility levels to control the behaviour of its commands. We currently recommend to use the level <emphasis>8</emphasis> which
|
| 608 |
|
|
is available in current <emphasis>Stable</emphasis> (Squeeze) and backported to <emphasis>Oldstable</emphasis>. However, there is no urgent need to
|
| 609 |
|
|
touch packages only because it has an older Debhelper version.</para>
|
| 610 |
tille |
6312 |
<para>
|
| 611 |
|
|
It is strongly recommended to use the short <emphasis>dh</emphasis> notation in <filename>debian/rules</filename> files which makes code factorisation very
|
| 612 |
plessy |
6376 |
simple and easy to understand the packaging for other members of the team. Even complex packaging becomes quite transparent this way.
|
| 613 |
tille |
6312 |
</para>
|
| 614 |
plessy |
1847 |
</sect2>
|
| 615 |
|
|
|
| 616 |
plessy |
6306 |
<sect2 id="cdbs">
|
| 617 |
plessy |
1847 |
<title>CDBS</title>
|
| 618 |
tille |
6313 |
<para>Before the short <emphasis>dh</emphasis> notation of debhelper existed CDBS was the only way to factorise code in <filename>debian/rules</filename> files.
|
| 619 |
|
|
So it was recommended in the past but it turned out that CDBS is badly documented and recently introduced incompatible changes. So it is sometimes reasonable
|
| 620 |
plessy |
6319 |
to switch from CDBS to <emphasis>dh</emphasis> if some problems in the packaging might occure.</para>
|
| 621 |
plessy |
1847 |
<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>
|
| 622 |
|
|
</sect2>
|
| 623 |
plessy |
6310 |
|
| 624 |
|
|
<sect2 id="vcs">
|
| 625 |
|
|
<title>Version control systems</title>
|
| 626 |
|
|
<para>
|
| 627 |
|
|
We are currently using two different version control systems, Subversion and Git.
|
| 628 |
|
|
</para>
|
| 629 |
|
|
<sect3 id="vcs-svn">
|
| 630 |
|
|
<title>Source package stored in a Subversion repository</title>
|
| 631 |
|
|
<para>
|
| 632 |
plessy |
6346 |
We use the <literal>MergeWithUpstream</literal> workflow, so please
|
| 633 |
|
|
keep all the modifications in the <filename
|
| 634 |
|
|
class="directory">debian</filename> directory, and use the
|
| 635 |
|
|
<option>-o</option> option of <command>svn-buildpackage</command>, as
|
| 636 |
|
|
in the following example: <code><command>svn-inject</command>
|
| 637 |
|
|
<option>-o</option> <filename>package.dsc</filename> <filename
|
| 638 |
|
|
class="directory">svn+ssh://svn.debian.org/svn/debian-med/trunk/packages/</filename></code>.
|
| 639 |
plessy |
6310 |
</para>
|
| 640 |
|
|
</sect3>
|
| 641 |
|
|
<sect3 id="vcs-git">
|
| 642 |
|
|
<title>Source package stored in a Git repository</title>
|
| 643 |
|
|
<para>
|
| 644 |
plessy |
6346 |
Git repositories should be stored in the <filename
|
| 645 |
|
|
class="directory">/git/debian-med</filename> directory on Alioth and
|
| 646 |
|
|
created with the <link
|
| 647 |
|
|
linkend="create-git-repository-on-alioth"><command>setup-repository</command></link>
|
| 648 |
plessy |
6375 |
script available there. There, they must give write access to the
|
| 649 |
|
|
<literal>debian-med</literal> Alioth group and all the Debian
|
| 650 |
plessy |
6376 |
Developers, with appropriate Unix permissions (including SGID bit on
|
| 651 |
plessy |
6375 |
directories) and ACLs. See <filename class="directory">/git/debian-med</filename>
|
| 652 |
|
|
itself as an example. <command>setup-repository</command> does this
|
| 653 |
|
|
automatically.
|
| 654 |
plessy |
6310 |
</para>
|
| 655 |
plessy |
6346 |
<para>
|
| 656 |
|
|
Git repositories managed with a helper tool should announce it. For
|
| 657 |
|
|
instance, to show that <command>git-buildpackage</command> is used,
|
| 658 |
|
|
the package can contain a configuration file in
|
| 659 |
|
|
<filename>debian/gbp.conf</filename>.
|
| 660 |
|
|
</para>
|
| 661 |
plessy |
6310 |
</sect3>
|
| 662 |
plessy |
6335 |
<sect3 id="vcs-tags">
|
| 663 |
|
|
<title>Tags</title>
|
| 664 |
|
|
<para>
|
| 665 |
|
|
Tags indicate the revision corresponding to uploaded packages. For
|
| 666 |
|
|
Subversion, the version number is used, and for Git,
|
| 667 |
|
|
<literal>debian/</literal> is added before the version number. In the
|
| 668 |
|
|
Subversion repository, older tags may be deleted to save space.
|
| 669 |
|
|
</para>
|
| 670 |
|
|
</sect3>
|
| 671 |
plessy |
6310 |
</sect2>
|
| 672 |
plessy |
6306 |
<sect2 id="new-package">
|
| 673 |
plessy |
6343 |
<title>New package</title>
|
| 674 |
plessy |
6325 |
<para>
|
| 675 |
plessy |
6346 |
Try to inject a new package only after successfully building it with
|
| 676 |
|
|
<command>dpkg-buildpackage</command> (or any wrapper around it). Use a
|
| 677 |
|
|
file like <filename>debian/DRAFT</filename> to mention when the package
|
| 678 |
|
|
is a draft.
|
| 679 |
plessy |
6325 |
</para>
|
| 680 |
plessy |
6343 |
</sect2>
|
| 681 |
|
|
<sect2 id="new-packages-in-tasks">
|
| 682 |
|
|
<title>The Debian Med Blend tasks</title>
|
| 683 |
|
|
<para>
|
| 684 |
|
|
Once you injected a new package please make sure that it is mentioned
|
| 685 |
plessy |
6376 |
in the appropriate <link linkend="tasks">tasks</link> file in the SVN
|
| 686 |
plessy |
6356 |
source of the <package>debian-med</package> Blend package. Some team
|
| 687 |
|
|
members watch the changes in the Debian Med packaging pool but it helps
|
| 688 |
|
|
if the maintainer of a new package verifies that everything is in the
|
| 689 |
|
|
right place.
|
| 690 |
plessy |
6343 |
</para>
|
| 691 |
|
|
</sect2>
|
| 692 |
plessy |
6339 |
<sect2 id="building-and-tagging">
|
| 693 |
|
|
<title>Building and tagging the packages</title>
|
| 694 |
|
|
<para>
|
| 695 |
|
|
We prefer that uploaded packages are built in a chroot, to provide
|
| 696 |
|
|
similar build environment to the whole team. After upload, please <link linkend="vcs-tags">tag</link>
|
| 697 |
|
|
the <link linkend="svn-tag-release">Suvbersion</link> or <link linkend="git-tag-release">Git</link> repository.
|
| 698 |
|
|
</para>
|
| 699 |
hanska-guest |
1277 |
</sect2>
|
| 700 |
plessy |
6306 |
<sect2 id="patches">
|
| 701 |
hanska-guest |
1277 |
<title>Handling patches</title>
|
| 702 |
plessy |
6330 |
<para>
|
| 703 |
|
|
Often happens that the upstream code doesn't fit well into the
|
| 704 |
|
|
Debian distribution: be this wrong paths, missing features, anything
|
| 705 |
|
|
that implies editing the source files. When you directly edit
|
| 706 |
|
|
upstream's source files, your changes will be put into a .diff.gz file
|
| 707 |
|
|
if you use the <literal>1.0</literal> source format and in a monolithic
|
| 708 |
|
|
patch if you use the <literal>3.0 (quilt)</literal> format. To better
|
| 709 |
|
|
organise the patches and group the by function, please use a patch
|
| 710 |
|
|
handling system which keeps patches under the <filename
|
| 711 |
|
|
class="directory">debian/patches</filename> directory.
|
| 712 |
|
|
</para>
|
| 713 |
|
|
<para>
|
| 714 |
|
|
The <literal>3.0 (quilt)</literal> Dpkg source format provides its own
|
| 715 |
|
|
patch system. Apart from this, the most popular is
|
| 716 |
|
|
<command>quilt</command>. <emphasis>simple-patchsys</emphasis>, from
|
| 717 |
|
|
the <package>CDBS</package> package, is deprecated since version
|
| 718 |
|
|
<literal>0.4.85</literal>. <command>dpatch</command> has been popular
|
| 719 |
|
|
as well, but is not compatible with the <literal>3.0 (quilt)</literal>
|
| 720 |
|
|
source format. Please don't use any other patch system in Debian Med,
|
| 721 |
|
|
unless absolutely necessary.
|
| 722 |
|
|
</para>
|
| 723 |
plessy |
6306 |
<sect3 id="quilt">
|
| 724 |
hanska-guest |
1277 |
<title>Using <command>quilt</command></title>
|
| 725 |
|
|
<para>Using quilt is rather easy.</para>
|
| 726 |
|
|
<para>First, make sure you have correctly setup quilt: open
|
| 727 |
|
|
<filename>.quiltrc</filename> in your home directory (create
|
| 728 |
|
|
it if you don't have one), and make sure it looks like this:</para>
|
| 729 |
|
|
<blockquote>
|
| 730 |
|
|
<programlisting>QUILT_DIFF_ARGS="--no-timestamps --no-index"
|
| 731 |
|
|
QUILT_REFRESH_ARGS="--no-timestamps --no-index"
|
| 732 |
|
|
QUILT_PATCHES="debian/patches"</programlisting>
|
| 733 |
|
|
</blockquote>
|
| 734 |
|
|
<para>After this, you're ready to start working with quilt.</para>
|
| 735 |
plessy |
6306 |
<sect4 id="quilt-create">
|
| 736 |
hanska-guest |
1277 |
<title>Creating a patch</title>
|
| 737 |
|
|
<para>To create a patch, use the <command>new</command> command.
|
| 738 |
|
|
Run:</para>
|
| 739 |
|
|
<blockquote>
|
| 740 |
|
|
<para><userinput>
|
| 741 |
|
|
<command>quilt new</command> <filename><patch_name>.patch</filename>
|
| 742 |
|
|
</userinput></para>
|
| 743 |
|
|
</blockquote>
|
| 744 |
|
|
<para>This will create (if it doesn't exist yet) a
|
| 745 |
|
|
<filename>debian/patches/series</filename> file, which
|
| 746 |
|
|
contains all the patches to be applied by quilt. Moreover,
|
| 747 |
|
|
the new patch is also the topmost (the currently
|
| 748 |
|
|
applied).</para>
|
| 749 |
|
|
<para>Now start editing files, with:</para>
|
| 750 |
|
|
<blockquote>
|
| 751 |
|
|
<para><userinput>
|
| 752 |
|
|
<command>quilt edit</command> <filename><file></filename>
|
| 753 |
|
|
</userinput></para>
|
| 754 |
|
|
</blockquote>
|
| 755 |
|
|
<para>and repeat the process for each file the patch is
|
| 756 |
|
|
involved with. At the end, run</para>
|
| 757 |
|
|
<blockquote>
|
| 758 |
|
|
<para><userinput>
|
| 759 |
|
|
<command>quilt refresh</command>
|
| 760 |
|
|
</userinput></para>
|
| 761 |
|
|
</blockquote>
|
| 762 |
|
|
<para>This will compare the noted state of the edited files
|
| 763 |
|
|
with the current state, and will produce a patch in
|
| 764 |
|
|
<filename>debian/patches</filename>. Remember: the patch
|
| 765 |
|
|
is currently applied (you can check this with
|
| 766 |
|
|
<command>quilt applied</command>).</para>
|
| 767 |
|
|
</sect4>
|
| 768 |
plessy |
6306 |
<sect4 id="quilt-apply">
|
| 769 |
hanska-guest |
1277 |
<title>Applying and unapplying patches</title>
|
| 770 |
|
|
<para>Just two easy commands to do the job:</para>
|
| 771 |
|
|
<itemizedlist>
|
| 772 |
|
|
<listitem><para><command>quilt pop</command> will unapply the topmost patch.</para></listitem>
|
| 773 |
|
|
<listitem><para><command>quilt push</command> will apply the next patch in debian/patches/series.</para></listitem>
|
| 774 |
|
|
</itemizedlist>
|
| 775 |
|
|
<para>You can just add a "-a" flag to the commands above, to
|
| 776 |
|
|
respectively apply/unapply all patches in the series.</para>
|
| 777 |
|
|
<tip>
|
| 778 |
|
|
<para>You can check which patches are applied/unapplied
|
| 779 |
|
|
with, respectively, <command>quilt applied</command> and
|
| 780 |
|
|
<command>quilt unapplied</command>.</para>
|
| 781 |
|
|
</tip>
|
| 782 |
|
|
</sect4>
|
| 783 |
plessy |
6306 |
<sect4 id="quilt-edit">
|
| 784 |
hanska-guest |
1277 |
<title>Editing patches</title>
|
| 785 |
|
|
<para>To edit a patch, first make it the topmost:</para>
|
| 786 |
|
|
<blockquote>
|
| 787 |
|
|
<para><userinput>
|
| 788 |
|
|
<command>quilt push</command> <filename><patch_name></filename>
|
| 789 |
|
|
</userinput></para>
|
| 790 |
|
|
</blockquote>
|
| 791 |
|
|
<para>If the patch is already applied, but is not the topmost,
|
| 792 |
|
|
run <command>quilt pop</command> until it becomes the currently
|
| 793 |
|
|
applied one.</para>
|
| 794 |
|
|
<para>You can now run <command>quilt edit</command> on the files
|
| 795 |
|
|
you want to change, and, when you're done, <command>quilt
|
| 796 |
|
|
refresh</command>.</para>
|
| 797 |
|
|
</sect4>
|
| 798 |
plessy |
6306 |
<sect4 id="quilt-rename">
|
| 799 |
hanska-guest |
1277 |
<title>Renaming patches</title>
|
| 800 |
|
|
<para>Sometimes it's useful to rename a patch. Without
|
| 801 |
|
|
any hassle, do:</para>
|
| 802 |
|
|
<blockquote>
|
| 803 |
|
|
<para><userinput>
|
| 804 |
|
|
<command>quilt rename -P</command> <filename><old_name>.patch</filename>
|
| 805 |
|
|
<filename><new_name>.patch</filename>
|
| 806 |
|
|
</userinput></para>
|
| 807 |
|
|
</blockquote>
|
| 808 |
|
|
</sect4>
|
| 809 |
plessy |
6306 |
<sect4 id="quilt-other">
|
| 810 |
hanska-guest |
1277 |
<title>Other commands</title>
|
| 811 |
|
|
<para>Please see <command>man 1 quilt</command> to have a
|
| 812 |
|
|
comprehensive list of commands.</para>
|
| 813 |
|
|
</sect4>
|
| 814 |
plessy |
6306 |
<sect4 id="quilt-integration">
|
| 815 |
hanska-guest |
1277 |
<title>Integration in the build process</title>
|
| 816 |
|
|
<para>Add in the very first part of <filename>debian/rules</filename>
|
| 817 |
|
|
(i.e. before the targets), the line:</para>
|
| 818 |
|
|
<blockquote>
|
| 819 |
|
|
<programlisting>include <filename class="headerfile">/usr/share/quilt/quilt.make</filename></programlisting>
|
| 820 |
|
|
</blockquote>
|
| 821 |
plessy |
1847 |
<para>Please use this to import patch and unpatch rules instead of writing them, and remember to add the needed dependencies to its
|
| 822 |
hanska-guest |
1277 |
targets:</para>
|
| 823 |
|
|
<blockquote>
|
| 824 |
|
|
<programlisting>...
|
| 825 |
|
|
build: patch build-stamp
|
| 826 |
|
|
build-stamp: configure
|
| 827 |
|
|
...</programlisting>
|
| 828 |
|
|
</blockquote>
|
| 829 |
|
|
<para>This kind of dependency will ensure that if you also
|
| 830 |
|
|
patch the build system, you get a working patched build
|
| 831 |
|
|
process.</para>
|
| 832 |
|
|
<caution>
|
| 833 |
|
|
<para>Don't also put configure as a dependency of
|
| 834 |
|
|
build (leave it in build-stamp): that may cause problems
|
| 835 |
|
|
during parallel buildings (i.e. the -j flag of make).</para>
|
| 836 |
|
|
</caution>
|
| 837 |
|
|
<para>Now add a dependency to the clean target:</para>
|
| 838 |
|
|
<blockquote>
|
| 839 |
|
|
<programlisting>...
|
| 840 |
|
|
clean: unpatch
|
| 841 |
|
|
...</programlisting>
|
| 842 |
|
|
</blockquote>
|
| 843 |
|
|
<para>If you've also patched the build system, using upstream's
|
| 844 |
|
|
clean target might fail. This is what you should do:</para>
|
| 845 |
|
|
<blockquote>
|
| 846 |
|
|
<programlisting>...
|
| 847 |
|
|
clean: clean-patched unpatch
|
| 848 |
|
|
clean-patched:
|
| 849 |
|
|
...</programlisting>
|
| 850 |
|
|
</blockquote>
|
| 851 |
|
|
<para>Obviously, you could always use an approach like this,
|
| 852 |
|
|
but it's an useless complication if you don't patch the build
|
| 853 |
|
|
system, and you should keep <filename>debian/rules</filename>
|
| 854 |
|
|
the simplest you can.</para>
|
| 855 |
|
|
</sect4>
|
| 856 |
|
|
</sect3>
|
| 857 |
plessy |
6306 |
<sect3 id="dpatch">
|
| 858 |
hanska-guest |
1277 |
<title>Using <command>dpatch</command></title>
|
| 859 |
plessy |
6306 |
<sect4 id="dpatch-create-patch">
|
| 860 |
hanska-guest |
1277 |
<title>Creating a patch</title>
|
| 861 |
|
|
<para>dpatch-edit-patch</para>
|
| 862 |
|
|
</sect4>
|
| 863 |
plessy |
6306 |
<sect4 id="dpatch-apply-unapply">
|
| 864 |
hanska-guest |
1277 |
<title>Applying and unapplying patches</title>
|
| 865 |
|
|
<para>apply(-all), unapply(-all), status</para>
|
| 866 |
|
|
</sect4>
|
| 867 |
plessy |
6306 |
<sect4 id="dpatch-edit-patch">
|
| 868 |
hanska-guest |
1277 |
<title>Editing patches</title>
|
| 869 |
|
|
<para>dpatch-edit-patch</para>
|
| 870 |
|
|
</sect4>
|
| 871 |
plessy |
6306 |
<sect4 id="dpatch-rename-patch">
|
| 872 |
hanska-guest |
1277 |
<title>Renaming patches</title>
|
| 873 |
|
|
<para>Is this possible?</para>
|
| 874 |
|
|
</sect4>
|
| 875 |
plessy |
6306 |
<sect4 id="dpatch-other">
|
| 876 |
hanska-guest |
1277 |
<title>Other commands</title>
|
| 877 |
|
|
<para>Please see <command>man 1 dpatch</command> for a
|
| 878 |
|
|
comprehensive list of commands.</para>
|
| 879 |
|
|
</sect4>
|
| 880 |
plessy |
6306 |
<sect4 id="dpatch-integration">
|
| 881 |
hanska-guest |
1277 |
<title>Integration in the build process</title>
|
| 882 |
|
|
<para>Follow the instructions for quilt and adapt the path of
|
| 883 |
|
|
inclusion to <filename class="headerfile">/usr/share/dpatch/dpatch.make</filename></para>
|
| 884 |
|
|
</sect4>
|
| 885 |
|
|
</sect3>
|
| 886 |
|
|
</sect2>
|
| 887 |
|
|
</sect1>
|
| 888 |
|
|
</article>
|
Parent Directory
| 
Revision Log