/[ddp]/manuals/trunk/developers-reference/pkgs.dbk

Diff of /manuals/trunk/developers-reference/pkgs.dbk

Parent Directory | Revision Log | View Patch Patch

-revision 5795 by lucas,
Thu Jan 22 23:30:41 2009 UTC
+revision 7071 by hertzog,
Sun Feb 14 17:46:38 2010 UTC
 Line 37 
 Please send a copy to &email-debian-deve
  header (don't use CC:, because that way the message's subject won't
  indicate the bug number). If you are packaging so many new packages (>10)
  that notifying the mailing list in seperate messages is too disruptive,
- do send a summary after filing the bugs to the debian-devel list instead.
+ send a summary after filing the bugs to the debian-devel list instead.
  This will inform the other developers about upcoming packages and will
  allow a review of your description and package name.
  </para>
  <para>
- Please include a <literal>Closes:
+ Please include a <literal>Closes: #<replaceable>nnnnn</replaceable></literal>
- bug#<replaceable>nnnnn</replaceable></literal> entry in the changelog of the
+ entry in the changelog of the new package in order for the bug report to
- new package in order for the bug report to be automatically closed once the new
+ be automatically closed once the new package is installed in the archive
- package is installed in the archive (see <xref linkend="upload-bugfix"/> ).
+ (see <xref linkend="upload-bugfix"/>).
+ </para>
+ <para>
+ If you think your package needs some explanations for the administrators of the
+ NEW package queue, include them in your changelog, send to ftpmaster@debian.org
+ a reply to the email you receive as a maintainer after your upload, or reply to
+ the rejection email in case you are already re-uploading.
  </para>
  <para>
  When closing security bugs include CVE numbers as well as the Closes: #nnnnn.
-Line 217 
 distinction between the original sources
+Line 223 
 distinction between the original sources
  <listitem>
  <para>
  the (more common) packages where there's an original source tarball file
- accompanied by another file that contains the patches applied for Debian
+ accompanied by another file that contains the changes made by Debian
  </para>
  </listitem>
  </itemizedlist>
  <para>
  For the native packages, the source package includes a Debian source control
  file (<literal>.dsc</literal>) and the source tarball
- (<literal>.tar.gz</literal>).  A source package of a non-native package
+ (<literal>.tar.{gz,bz2,lzma}</literal>). A source package of a non-native package
  includes a Debian source control file, the original source tarball
- (<literal>.orig.tar.gz</literal>) and the Debian patches
+ (<literal>.orig.tar.{gz,bz2,lzma}</literal>) and the Debian changes
- (<literal>.diff.gz</literal>).
+ (<literal>.diff.gz</literal> for the source format “1.0” or
+ <literal>.debian.tar.{gz,bz2,lzma}</literal> for the source format “3.0 (quilt)”).
  </para>
  <para>
- Whether a package is native or not is determined when it is built by
+ With source format “1.0”, whether a package is native or not was determined
- <citerefentry> <refentrytitle>dpkg-buildpackage</refentrytitle>
+ by <command>dpkg-source</command> at build time. Nowadays it is recommended
- <manvolnum>1</manvolnum> </citerefentry>.  The rest of this section relates
+ to be explicit about the desired source format by putting either “3.0 (quilt)”
- only to non-native packages.
+ or “3.0 (native)” in <filename>debian/source/format</filename>.
+ The rest of this section relates only to non-native packages.
  </para>
  <para>
  The first time a version is uploaded which corresponds to a particular upstream
-Line 245 
 will not need to be re-uploaded.
+Line 253 
 will not need to be re-uploaded.
  <para>
  By default, <command>dpkg-genchanges</command> and
  <command>dpkg-buildpackage</command> will include the original source tar file
- if and only if the Debian revision part of the source version number is 0 or 1,
+ if and only if the current changelog entry has a different upstream version
- indicating a new upstream version.  This behavior may be modified by using
+ from the preceding entry. This behavior may be modified by using
  <literal>-sa</literal> to always include it or <literal>-sd</literal> to always
  leave it out.
  </para>
-Line 259 
 the archive.
+Line 267 
 the archive.
  </para>
  <para>
  Please notice that, in non-native packages, permissions on files that are not
- present in the .orig.tar.gz will not be preserved, as diff does not store file
+ present in the .orig.tar.{gz,bz2} will not be preserved, as diff does not store file
- permissions in the patch.
+ permissions in the patch. However when using source format “3.0 (quilt)”,
+ permissions of files inside the <filename>debian</filename> directory are
+ preserved since they are stored in a tar archive.
  </para>
  </section>
-Line 291 
 time.
+Line 301 
 time.
  <title>Special case: uploads to the <literal>stable</literal> and
  <literal>oldstable</literal> distributions</title>
  <para>
- Uploading to <literal>stable</literal> means that the package will transfered
+ Uploading to <literal>stable</literal> means that the package will transferred
  to the <literal>proposed-updates-new</literal> queue for review by the stable
  release managers, and if approved will be installed in
  <filename>stable-proposed-updates</filename> directory of the Debian archive.
-Line 376 
 section</link> for details.
+Line 386 
 section</link> for details.
  <title>Uploading to <literal>ftp-master</literal></title>
  <para>
  To upload a package, you should upload the files (including the signed changes
- and dsc-file) with anonymous ftp to <literal>&ftp-master-host;</literal> in
+ and dsc-file) with anonymous ftp to <literal>&ftp-upload-host;</literal> in
  the directory <ulink
- url="ftp://&ftp-master-host;&upload-queue;">&upload-queue;</ulink>.
+ url="ftp://&ftp-upload-host;&upload-queue;">&upload-queue;</ulink>.
  To get the files processed there, they need to be signed with a key in the
  Debian Developers keyring or the Debian Maintainers keyring
  (see <ulink url="&url-wiki-dm;"></ulink>).
-Line 394 
 linkend="dput"/> useful when uploading p
+Line 404 
 linkend="dput"/> useful when uploading p
  automate the process of uploading packages into Debian.
  </para>
  <para>
- For removing packages, please see the README file in that ftp directory, and
+ For removing packages, please see
+ <ulink url="ftp://&ftp-upload-host;&upload-queue;/README"/> and
  the Debian package <xref linkend="dcut"/> .
  </para>
  </section>
-Line 416 
 the deferred uploads queue"</ulink>.
+Line 427 
 the deferred uploads queue"</ulink>.
  When the specified waiting time is over, the package is moved into
  the regular incoming directory for processing.
  This is done through automatic uploading to
- <literal>&ftp-master-host;</literal> in upload-directory
+ <literal>&ftp-upload-host;</literal> in upload-directory
  <literal>DELAYED/[012345678]-day</literal>. 0-day is uploaded
- multiple times per day to <literal>&ftp-master-host;</literal>.
+ multiple times per day to <literal>&ftp-upload-host;</literal>.
  </para>
  <para>
  With dput, you can use the <literal>--delayed <replaceable>DELAY</replaceable></literal>
-Line 441 
 see section <xref linkend="bug-security"
+Line 452 
 see section <xref linkend="bug-security"
  <section id="s5.6.5">
  <title>Other upload queues</title>
  <para>
- The scp queues on <literal>&ftp-master-host;</literal>, and <literal>
+ There is an alternative upload queue in Europe at <ulink
- security.debian.org</literal> are mostly unusable due to the login restrictions
+ url="ftp://&ftp-eu-upload-host;&upload-queue;"/>. It operates in
- on those hosts.
+ the same way as <literal>&ftp-upload-host;</literal>, but should be faster
- </para>
+ for European developers.
- <para>
- The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are currently
- down.  Work is underway to resurrect them.
  </para>
  <para>
- The queues on master.debian.org, samosa.debian.org, master.debian.or.jp, and
+ Packages can also be uploaded via ssh to
- ftp.chiark.greenend.org.uk are down permanently, and will not be resurrected.
+ <literal>&ssh-upload-host;</literal>; files should be put
- The queue in Japan will be replaced with a new queue on hp.debian.or.jp some
+ <literal>/srv/upload.debian.org/UploadQueue</literal>. This queue does
- day.
+ not support <xref linkend="delayed-incoming">delayed uploads</xref>.
  </para>
  </section>
-Line 511 
 file</literal>.
+Line 519 
 file</literal>.
  <para>
  To alter the actual section that a package is put in, you need to first make
  sure that the <filename>debian/control</filename> file in your package is
- accurate.  Next, send an email &email-override; or submit a
+ accurate.  Next, submit a
  bug against <systemitem role="package">ftp.debian.org</systemitem> 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.
+ or priority to the new one. Use a Subject like
+ <literal>override: PACKAGE1:section/priority, [...],
+   PACKAGEX:section/priority</literal>, and include the justification for the
+ change in the body of the bug report.
  </para>
  <para>
  For more information about <literal>override files</literal>, see
-Line 827 
 outstanding security problems, helping m
+Line 838 
 outstanding security problems, helping m
  fixing them themselves, sending security advisories, and maintaining
  <literal>security.debian.org</literal>.
  </para>
- <!-- information about the security database goes here once it's ready -->
- <!-- (mdz) -->
  <para>
  When you become aware of a security-related bug in a Debian package, whether or
  not you are the maintainer, collect pertinent information about the problem,
  and promptly contact the security team at
  &email-security-team; as soon as possible.  <emphasis
- role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal>;
+ role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal>
-  the security team will do that.  Useful information includes, for example:
+ without contacting the team.  Useful information includes, for example:
  </para>
  <itemizedlist>
  <listitem>
-Line 870 
 linkend="bug-security-advisories"/> )
+Line 879 
 linkend="bug-security-advisories"/> )
  </para>
  </listitem>
  </itemizedlist>
+ <para>As the maintainer of the package, you have the responsibility to
+ maintain it, even in the stable release. You are in the best position
+ to evaluate patches and test updated packages, so please see the sections
+ below on how to prepare packages for the Security Team to handle.</para>
+ <section id="bug-security-tracker">
+ <title>The Security Tracker</title>
+ <para>
+ The security team maintains a central database, the
+ <ulink url="http://security-tracker.debian.org/">Debian Security Tracker</ulink>.
+ This contains all public information that is known about security issues:
+ which packages and versions are affected or fixed, and thus whether stable,
+ testing and/or unstable are vulnerable. Information that is still confidential
+ is not added to the tracker.
+ </para>
+ <para>
+ You can search it for a specific issue, but also on package name. Look
+ for your package to see which issues are still open. If you can, please provide
+ more information about those issues, or help to address them in your package.
+ Instructions are on the tracker web pages.
+ </para>
+ </section>
  <section id="bug-security-confidentiality">
  <title>Confidentiality</title>
  <para>
-Line 939 
 There are two reasons for releasing info
+Line 971 
 There are two reasons for releasing info
  requested: the problem has been known for a while, or the problem or exploit
  has become public.
  </para>
+ <para>
+ The Security Team has a PGP-key to enable encrypted communication about
+ sensitive issues. See the <ulink url="http://www.debian.org/security/faq#contact">Security Team FAQ</ulink> for details.
+ </para>
  </section>
  <section id="bug-security-advisories">
-Line 1075 
 Be sure to verify the following items:
+Line 1111 
 Be sure to verify the following items:
  <itemizedlist>
  <listitem>
  <para>
- Target the right distribution in your <filename>debian/changelog</filename>.
+ <emphasis role="strong">Target the right distribution</emphasis>
+ in your <filename>debian/changelog</filename>.
  For <literal>stable</literal> this is <literal>stable-security</literal> and
- for testing this is <literal>testing-security</literal>, and for the previous
+ for <literal>testing</literal> this is <literal>testing-security</literal>, and for the previous
  stable release, this is <literal>oldstable-security</literal>.  Do not target
  <replaceable>distribution</replaceable><literal>-proposed-updates</literal> or
  <literal>stable</literal>!
-Line 1085 
 stable release, this is <literal>oldstab
+Line 1122 
 stable release, this is <literal>oldstab
  </listitem>
  <listitem>
  <para>
- The upload should have urgency=high.
+ The upload should have <emphasis role="strong">urgency=high</emphasis>.
  </para>
  </listitem>
  <listitem>
  <para>
  Make descriptive, meaningful changelog entries.  Others will rely on them to
- determine whether a particular bug was fixed.  Always include an external
+ determine whether a particular bug was fixed.  Add <literal>closes:</literal>
- reference, preferably a CVE identifier, so that it can be cross-referenced.
+ statements for any <emphasis role="strong">Debian bugs</emphasis> filed.
- Include the same information in the changelog for <literal>unstable</literal>,
+ Always include an external reference, preferably a <emphasis role="strong">CVE
- so that it is clear
+ identifier</emphasis>, so that it can be cross-referenced. However, if a CVE
- that the same bug was fixed, as this is very helpful when verifying that the
+ identifier has not yet been assigned, do not wait for it but continue the
- bug is fixed in the next stable release.  If a CVE identifier has not yet been
+ process. The identifier can be cross-referenced later.
- assigned, the security team will request one so that it can be included in the
- package and in the advisory.
- </para>
- </listitem>
- <listitem>
- <para>
- Make sure the version number is proper.  It must be greater than the current
- package, but less than package versions in later distributions.  If in doubt,
- test it with <literal>dpkg --compare-versions</literal>.  Be careful not to
- re-use a version number that you have already used for a previous upload.  For
- <literal>testing</literal>, there must be a higher version in
- <literal>unstable</literal>.  If there is none yet (for example, if
- <literal>testing</literal> and <literal>unstable</literal> have the same
- version) you must upload a new version to <literal>unstable</literal> first.
  </para>
  </listitem>
  <listitem>
  <para>
- Do not make source-only uploads if your package has any binary-all packages (do
+ Make sure the <emphasis role="strong">version number</emphasis> is proper.
- not use the <literal>-S</literal> option to
+ It must be greater than the current package, but less than package versions in
- <command>dpkg-buildpackage</command>).  The <command>buildd</command>
+ later distributions.  If in doubt, test it with <literal>dpkg
- infrastructure will not build those.  This point applies to normal package
+ --compare-versions</literal>.  Be careful not to re-use a version number that
- uploads as well.
+ you have already used for a previous upload, or one that conflicts with a
+ binNMU. The convention is to append
+ <literal>+</literal><replaceable>codename</replaceable><literal>1</literal>, e.g.
+ <literal>1:2.4.3-4+etch1</literal>, of course increasing 1 for any subsequent
+ uploads.
  </para>
  </listitem>
  <listitem>
  <para>
  Unless the upstream source has been uploaded to <literal>security.debian.org
- </literal> before (by a previous security update), build the upload with full
+ </literal> before (by a previous security update), build the upload <emphasis
- upstream source (<literal>dpkg-buildpackage -sa</literal>).  If there has been
+ role="strong">with full upstream source</emphasis> (<literal>dpkg-buildpackage
- a previous upload to <literal>security.debian.org</literal> with the same
+ -sa</literal>).  If there has been a previous upload to
- upstream version, you may upload without upstream source (<literal>
+ <literal>security.debian.org</literal> with the same upstream version, you may
- dpkg-buildpackage -sd</literal>).
+ upload without upstream source (<literal> dpkg-buildpackage -sd</literal>).
  </para>
  </listitem>
  <listitem>
  <para>
- Be sure to use the exact same <filename>*.orig.tar.gz</filename> as used in the
+ Be sure to use the <emphasis role="strong">exact same
+ <filename>*.orig.tar.{gz,bz2}</filename></emphasis> as used in the
  normal archive, otherwise it is not possible to move the security fix into the
  main archives later.
  </para>
  </listitem>
  <listitem>
  <para>
- Build the package on a clean system which only has packages installed from the
+ Build the package on a <emphasis role="strong">clean system</emphasis> which only
- distribution you are building for.  If you do not have such a system yourself,
+ has packages installed from the distribution you are building for. If you do not
- you can use a debian.org machine (see <xref linkend="server-machines"/> ) or
+ have such a system yourself, you can use a debian.org machine (see
- setup a chroot (see <xref linkend="pbuilder"/> and <xref
+ <xref linkend="server-machines"/> ) or setup a chroot (see
- linkend="debootstrap"/> ).
+ <xref linkend="pbuilder"/> and <xref linkend="debootstrap"/> ).
  </para>
  </listitem>
  </itemizedlist>
-Line 1178 
 archives.  For security uploads, the pla
+Line 1206 
 archives.  For security uploads, the pla
  </para>
  <para>
  Once an upload to the security queue has been accepted, the package will
- automatically be rebuilt for all architectures and stored for verification by
+ automatically be built for all architectures and stored for verification by
  the security team.
  </para>
  <para>
-Line 1220 
 control information to place the package
+Line 1248 
 control information to place the package
  the package (see the <ulink
  url="&url-debian-policy;">Debian Policy Manual</ulink> for
  details).  You must ensure that you include the
- <filename>.orig.tar.gz</filename> in your upload (even if you are not uploading
+ <filename>.orig.tar.{gz,bz2}</filename> in your upload (even if you are not uploading
  a new upstream version), or it will not appear in the new section together with
  the rest of the package.  If your new section is valid, it will be moved
  automatically.  If it does not, then contact the ftpmasters in order to
-Line 1321 
 should either be reassigned to another p
+Line 1349 
 should either be reassigned to another p
  code has evolved into another package (e.g.  <literal>libfoo12</literal> was
  removed because <literal>libfoo13</literal> supersedes it) or closed if the
  software is simply no longer part of Debian.
+ When closing the bugs,
+ to avoid marking the bugs as fixed in versions of the packages
+ in previous Debian releases, they should be marked as fixed
+ in the version <literal>&lt;most-recent-version-ever-in-Debian&gt;+rm</literal>.
  </para>
  <section id="s5.9.2.1">
  <title>Removing packages from <filename>Incoming</filename></title>
-Line 1365 
 Note that this applies to each part of y
+Line 1397 
 Note that this applies to each part of y
  you wish to replace the upstream source tarball of your package, you will need
  to upload it with a different version.  An easy possibility is to replace
  <filename>foo_1.00.orig.tar.gz</filename> with
- <filename>foo_1.00+0.orig.tar.gz</filename>.  This restriction gives each file
+ <filename>foo_1.00+0.orig.tar.gz</filename> or
- on the ftp site a unique name, which helps to ensure consistency across the
+ <filename>foo_1.00.orig.tar.bz2</filename>.  This restriction gives each
- mirror network.
+ file on the ftp site a unique name, which helps to ensure consistency
+ across the mirror network.
  </para>
  </section>
-Line 1764 
 flavor of Debian built with <command>gcc
+Line 1797 
 flavor of Debian built with <command>gcc
  also enable Debian to recompile entire distributions quickly.
  </para>
  <para>
- The buildds admins of each arch can be contacted at the mail address
+ The wanna-build team, in charge of the buildds,
- <literal><replaceable>arch</replaceable>@buildd.debian.org</literal>.
+ can be reached at <literal>debian-wb-team@lists.debian.org</literal>.
+ To determine who (wanna-build team, release team) and how (mail, BTS)
+ to contact, refer to <ulink url="&url-wb-team;"></ulink>.
+ </para>
+ <para>
+ When requesting binNMUs or give-backs (retries after a failed build),
+ please use the format described at <ulink url="&url-release-wb;"/>.
  </para>
  </section>
  </section>
-Line 1806 
 fail also, and indicate this to a human
+Line 1847 
 fail also, and indicate this to a human
  In order to prevent autobuilders from needlessly trying to build your package,
  it must be included in <filename>packages-arch-specific</filename>, a list used
  by the <command>wanna-build</command> script.  The current version is available
- as <ulink
+ as <ulink url="&url-buildd-p-a-s;"/>;
- url="&url-cvsweb;srcdep/Packages-arch-specific?cvsroot=dak"></ulink>;
  please see the top of the file for whom to contact for changes.
  </para>
  </listitem>
-Line 1966 
 upload.  The first line of this entry mu
+Line 2006 
 upload.  The first line of this entry mu
  </screen>
  <para>
- The version must be the version of the last maintainer upload, plus
+ The way to version NMUs differs for native and non-native packages.
+ </para>
+ <para>
+ If the package is a native package (without a debian revision in the version number),
+ the version must be the version of the last maintainer upload, plus
  <literal>+nmu<replaceable>X</replaceable></literal>, where
- <replaceable>X</replaceable> is a counter starting at <literal>1</literal>.  If
+ <replaceable>X</replaceable> is a counter starting at <literal>1</literal>.
+ If
  the last upload was also an NMU, the counter should be increased.  For example,
- if the current version is <literal>1.5-1</literal>, then an NMU would get
+ if the current version is <literal>1.5</literal>, then an NMU would get
- version <literal>1.5-1+nmu1</literal>.  If the current version is
+ version <literal>1.5+nmu1</literal>.
- <literal>1.5+nmu3</literal> (a native package which has already been NMUed), the
+ </para>
- NMU would get version <literal>1.5+nmu4</literal>.  If a new upstream version
+ <para>
+ If the package is a not a native package, you should add a minor version number
+ to the debian revision part of the version number (the portion after the last
+ hyphen). This extra number must start at 1.  For example,
+ if the current version is <literal>1.5-2</literal>, then an NMU would get
+ version <literal>1.5-2.1</literal>. If a new upstream version
  is packaged in the NMU, the debian revision is set to <literal>0</literal>, for
- example <literal>1.6-0+nmu1</literal>.
+ example <literal>1.6-0.1</literal>.
+ </para>
+ <para>
+ In both cases, if the last upload was also an NMU, the counter should
+ be increased. For example, if the current version is
+ <literal>1.5+nmu3</literal> (a native package which has already been
+ NMUed), the NMU would get version <literal>1.5+nmu4</literal>.  .
  </para>
  <para>
  A special versioning scheme is needed to avoid disrupting the maintainer's
  work, since using an integer for the Debian revision will potentially

 Legend:



Removed from v.5795
 


changed lines


 
Added in v.7071
 Legend:



Removed from v.5795
 


changed lines


 
Added in v.7071
-Removed from v.5795
+Added in v.7071

	ViewVC Help
Powered by ViewVC 1.1.5