<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.176 $">
+ <!entity cvs-rev "$Revision: 1.179 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<p>
You have to keep the information available there up-to-date.
+
<sect id="key-maint">Maintaining your public key
<p>
Be very careful with your private keys. Do not place them on any
<sect id="voting">Voting
<p>
-Even if Debian is not always a real democracy, Debian has democratic
-tools and uses a democratic process to elect its leader or
-to approve a general resolution. Those processes are described in
-the <url id="&url-constitution;" name="Debian Constitution">.
+Even though Debian isn't really a democracy, we use a democratic
+process to elect our leaders and to approve general resolutions.
+These procedures are defined by the
+<url id="&url-constitution;" name="Debian Constitution">.
+ <p>
+Other than the yearly leader election, votes are not routinely held, and
+they are not undertaken lightly. Each proposal is first discussed on
+the &email-debian-vote; mailing list and it requires several endorsements
+before the project secretary starts the voting procedure.
<p>
-Democratic processes work well only if everybody take part in the
-vote, that's why you have to vote. To be able to vote you have to
-subscribe to &email-debian-devel-announce; since call for votes are sent
-there. If you want to follow the debate preceding a vote, you
-may want to subscribe to &email-debian-vote;.
+You don't have to track the pre-vote discussions, as the secretary will
+issue several calls for votes on &email-debian-devel-announce; (and all
+developers are expected to be subscribed to that list). Democracy doesn't
+work well if people don't take part in the vote, which is why we encourage
+all developers to vote. Voting is conducted via GPG-signed/encrypted emails
+messages.
<p>
The list of all the proposals (past and current) is available on the
-<url id="&url-vote;" name="Debian Voting Information"> page. You will find
-there additional information about how to make a vote proposal.
+<url id="&url-vote;" name="Debian Voting Information"> page, along with
+information on how to make, second and vote on proposals.
<sect id="inform-vacation">Going on vacation gracefully
<p>
-Most developers take vacations, and usually this means that they can't
-work for Debian and they can't be reached by email if any problem occurs.
-The other developers need to know that you're on vacation so that they'll
-do whatever is needed when such a problem occurs. Usually this means that
-other developers are allowed to NMU (see <ref id="nmu">) your package if a
-big problem (release critical bugs, security update, etc.) occurs while
-you're on vacation.
+It is common for developers to have periods of absence, whether those are
+planned vacations or simply being buried in other work. The important thing
+to notice is that the other developers need to know that you're on vacation
+so that they can do whatever is needed if a problem occurs with your
+packages or other duties in the project.
+ <p>
+Usually this means that other developers are allowed to NMU (see
+<ref id="nmu">) your package if a big problem (release critical bugs,
+security update, etc.) occurs while you're on vacation. Sometimes it's
+nothing as critical as that, but it's still appropriate to let the others
+know that you're unavailable.
<p>
In order to inform the other developers, there's two things that you should do.
-First send a mail to &email-debian-private; giving the period of time when
-you will be on vacation. You can also give some special instructions on what to
-do if any problem occurs. Be aware that some people don't care for vacation
-notices and don't want to read them; you should prepend "[VAC] " to the
-subject of your message so that it can be easily filtered.
+First send a mail to &email-debian-private; with "[VAC] " prepended to the
+subject of your message<footnote>This is so that the message can be easily
+filtered by people who don't want to read vacation notices.</footnote>,
+giving the period of time when you will be on vacation. You can also give
+some special instructions on what to do if a problem occurs.
<p>
-Next you should update your information
-available in the Debian LDAP database and mark yourself as ``on vacation''
-(this information is only accessible to debian developers). Don't forget
-to remove the ``on vacation'' flag when you come back!
+The other thing to do is to mark yourself as "on vacation" in the
+<qref id="devel-db">Debian developers' LDAP database</qref> (this
+information is only accessible to Debian developers).
+Don't forget to remove the "on vacation" flag when you come back!
+
<sect id="upstream-coordination">Coordination with upstream developers
<p>
modify the sources of the next upstream version. Whatever changes you
need, always try not to fork from the upstream sources.
+
<sect id="rc-bugs">Managing release-critical bugs
<p>
Generally you should deal with bug reports on your packages as described in
<p>
The <file>debian/changelog</file> file conforms to a certain structure,
with a number of different fields. One field of note, the
-<em>distribution</em>, is described in <ref id="upload-dist">. More
+<em>distribution</em>, is described in <ref id="distribution">. More
information about the structure of this file can be found in
the Debian Policy section titled "<file>debian/changelog</file>".
<p>
See also <ref id="bpp-debian-changelog">.
- <sect id="upload">Package uploads
-
- <p>
-When a package is uploaded to the Debian archive, it must be accompanied by
-a <tt>.changes</tt> control file, which gives directions to the archive
-maintenance software for its handling. This is generated by
-<prgn>dpkg-genchanges</prgn> during the normal package build process.
-
- <sect1 id="upload-checking">Checking the package prior to upload
- <p>
+ <sect id="sanitycheck">Testing the package
+ <p>
Before you upload your package, you should do basic testing on it. At
a minimum, you should try the following activities (you'll need to
have an older version of the same Debian package around):
</list>
- <sect1>Layout of the source files
+ <sect id="sourcelayout">Layout of the source package
+ <p>
There are two types of Debian source packages:
- <list>
+ <list>
<item>the so-called <em>native</em> packages, where there is no
distinction between the original sources and the patches
applied for Debian
<item>the (more common) packages where there's an original source
tarball file accompanied by another file that contains the
patches applied for Debian
- </list>
+ </list>
+ <p>
For the native packages, the source package includes a Debian source control
file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
package of a non-native package includes a Debian source control file, the
original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
(<tt>.diff.gz</tt>).
+ <p>
Whether a package is native or not is determined when it is built by
<manref name="dpkg-buildpackage" section="1">. The rest of this section
relates only to non-native packages.
+ <p>
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
included in the <file>.changes</file> file. Subsequently, this very same
tar file should be used to build the new diffs and <file>.dsc</file>
files, and will not need to be re-uploaded.
+ <p>
By default, <prgn>dpkg-genchanges</prgn> and
<prgn>dpkg-buildpackage</prgn> will include the original source tar
file if and only if the Debian revision part of the source version
number is 0 or 1, indicating a new upstream version. This behavior
may be modified by using <tt>-sa</tt> to always include it or
<tt>-sd</tt> to always leave it out.
+ <p>
If no original source is included in the upload, the original
source tar-file used by <prgn>dpkg-source</prgn> when constructing the
<file>.dsc</file> file and diff to be uploaded <em>must</em> be
byte-for-byte identical with the one already in the archive.
- <sect1 id="upload-dist">Picking a distribution
+ <sect id="distribution">Picking a distribution
+ <p>
Each upload needs to specify which distribution the package is intended
for. The package build process extracts this information from the first
line of the <file>debian/changelog</file> file and places it in the
<tt>Distribution</tt> field of the <tt>.changes</tt> file.
+ <p>
There are several possible values for this field: `stable', `unstable',
`testing-proposed-updates' and `experimental'. Normally, packages are
uploaded into <em>unstable</em>.
+ <p>
Actually, there are two other possible distributions: `stable-security' and
`testing-security', but read <ref id="bug-security"> for more information on
those.
+ <p>
It is technically possible to upload a package into several distributions
at the same time but it usually doesn't make sense to use that feature
because the dependencies of the package may vary with the distribution.
In particular, it never makes sense to combine the <em>experimental</em>
distribution with anything else.
- <sect2 id="upload-stable">Uploading to <em>stable</em>
+ <sect1 id="upload-stable">Uploads to <em>stable</em>
+ <p>
Uploading to <em>stable</em> means that the package will be placed into the
<file>stable-proposed-updates</file> directory of the Debian archive for further
testing before it is actually included in <em>stable</em>.
+ <p>
Extra care should be taken when uploading to <em>stable</em>. Basically, a
package should only be uploaded to stable if one of the following happens:
<list>
<item>the package becomes uninstallable
<item>a released architecture lacks the package
</list>
+ <p>
It is discouraged to change anything else in the package that isn't
important, because even trivial fixes can cause bugs later on. Uploading
new upstream versions to fix security problems is deprecated; applying the
specific patch from the new upstream version to the old one ("back-porting"
the patch) is the right thing to do in most cases.
+ <p>
Packages uploaded to <em>stable</em> need to be compiled on systems running
<em>stable</em>, so that their dependencies are limited to the libraries
(and other packages) available in <em>stable</em>; for example, a package
exists in unstable will be rejected. Making changes to dependencies of other
packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
those other packages uninstallable, is strongly discouraged.
+ <p>
The Release Team (which can be reached at &email-debian-release;) will
regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
your package can be included in <em>stable</em>. Please be clear (and
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
- <sect2 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
+ <sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em>
+ <p>
The testing distribution is fed with packages from unstable according to the rules
explained in <ref id="testing">. However, the release manager may stop the testing
scripts when he wants to freeze the distribution. In that case, you may want to
upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
+ <p>
Keep in mind that packages uploaded there are not automatically processed, they
have to go through the hands of the release manager. So you'd better have a good
reason to upload there. In order to know what a good reason is in the
release manager's eyes, you should read the instructions that he regularly
gives on &email-debian-devel-announce;.
+ <p>
You should not upload to <em>testing-proposed-updates</em> when you can update your
packages through <em>unstable</em>. If you can't (for example because you have a
newer development version in unstable), you may use it but it is recommended to ask
the authorization of the release manager before.
- <sect1 id="uploading">Uploading a package
+ <sect id="upload">Uploading a package
- <sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
+ <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
<p>
To upload a package, you need a personal account on
<ftpsite>&ftp-master-host;</ftpsite>, which you should have as an
official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
to transfer the files, place them into &us-upload-dir;;
if you use anonymous FTP to upload, place them into
-&upload-queue;. Please note that you should transfer
+&upload-queue;.
+ <p>
+Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
all files have been uploaded. If you don't want to bother with transferring
<p>
After uploading your package, you can check how the archive
maintenance software will process it by running <prgn>dinstall</prgn>
-on your changes file: <example>dinstall -n foo.changes</example>.
+on your changes file:
+<example>dinstall -n foo.changes</example>
+ <p>
Note that <prgn>dput</prgn> can do this for you automatically.
- <sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
+ <sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
<p>
As discussed above, export controlled software should not be uploaded
to <tt>ftp-master</tt>. Instead, upload the package to
residents consult a lawyer before doing uploads to non-US.
- <sect2>Uploads via <tt>chiark</tt>
+ <sect1>Uploads via <tt>chiark</tt>
<p>
If you have a slow network connection to <tt>ftp-master</tt>, there are
alternatives. One is to upload files to <file>Incoming</file> via a
program for details.
- <sect2>Uploads via <tt>erlangen</tt>
+ <sect1>Uploads via <tt>erlangen</tt>
<p>
Another upload queue is available in Germany: just upload the files
via anonymous FTP to <url id="&url-upload-erlangen;">.
the program for details.
- <sect2>Other upload queues
+ <sect1>Other upload queues
<p>
Another upload queue is available which is based in the US, and is a
good backup when there are problems reaching <tt>ftp-master</tt>. You can
The installation notification also includes information on what
section the package was inserted into. If there is a disparity, you
will receive a separate email notifying you of that. Read on below.
+ <p>
+Note also that if you upload via queues, the queue daemon software will
+also send you a notification by email.
- <sect1 id="override-file">Determining section and priority of a package
+ <sect id="override-file">Determining section and priority of a package
+ <p>
The <file>debian/control</file> file's <tt>Section</tt> and
<tt>Priority</tt> fields do not actually specify where the file will
be placed in the archive, nor its priority. In order to retain the
overall integrity of the archive, it is the archive maintainers who
have control over these fields. The values in the
<file>debian/control</file> file are actually just hints.
+ <p>
The archive maintainers keep track of the canonical sections and
priorities for packages in the <em>override file</em>. If there is a
disparity between the <em>override file</em> and the package's fields
archive. You can either correct your <file>debian/control</file> file
for your next upload, or else you may wish to make a change in the
<em>override file</em>.
+ <p>
To alter the actual section that a package is put in, you need to
first make sure that the <file>debian/control</file> in your package
is accurate. Next, send an email &email-override; or submit a bug
against <package>ftp.debian.org</package> requesting that the section
or priority for your package be changed from the old section or
priority to the new one. Be sure to explain your reasoning.
+ <p>
For more information about <em>override files</em>, see <manref
name="dpkg-scanpackages" section="8"> and
<url id="&url-bts-devel;#maintincorrect">.
Wait a few more days. If you still haven't got an answer from the
maintainer, send him a mail announcing your intent to NMU the package.
Prepare an NMU as described in <ref id="nmu-guidelines">, test it
-carefully on your machine (cf. <ref id="upload-checking">).
+carefully on your machine (cf. <ref id="sanitycheck">).
Double check that your patch doesn't have any unexpected side effects.
Make sure your patch is as small and as non-disruptive as it can be.
<item>
<sect2 id="nmu-build">Building source NMUs
<p>
Source NMU packages are built normally. Pick a distribution using the
-same rules as found in <ref id="upload-dist">. Just as described in
-<ref id="uploading">, a normal changes file, etc., will be built. In
-fact, all the prescriptions from <ref id="upload"> apply.
+same rules as found in <ref id="distribution">, follow the other
+prescriptions in <ref id="upload">.
<p>
Make sure you do <em>not</em> change the value of the maintainer in
the <file>debian/control</file> file. Your name as given in the NMU entry of
option provides detailed explanations of what each error or warning means,
what is its basis in Policy, and commonly how you can fix the problem.
<p>
-Refer to <ref id="upload-checking"> for more information on how and when
+Refer to <ref id="sanitycheck"> for more information on how and when
to use Lintian.
<p>
You can also see a summary of all problems reported by Lintian on your
~ianmdlvl / developers-reference.git / blobdiff