| 28 |
current URL where it can be downloaded from. |
current URL where it can be downloaded from. |
| 29 |
</para> |
</para> |
| 30 |
<para> |
<para> |
| 31 |
You should set the subject of the bug to ``ITP: <replaceable>foo</replaceable> |
You should set the subject of the bug to <literal>ITP: |
| 32 |
-- <replaceable>short description</replaceable>'', substituting the name of the |
<replaceable>foo</replaceable> -- <replaceable>short |
| 33 |
new package for <replaceable>foo</replaceable>. The severity of the bug report |
description</replaceable></literal>, substituting the name of the new |
| 34 |
must be set to <literal>wishlist</literal>. If you feel it's necessary, send |
package for <replaceable>foo</replaceable>. |
| 35 |
a copy to &email-debian-devel; by putting the address in the |
The severity of the bug report must be set to <literal>wishlist</literal>. |
| 36 |
<literal>X-Debbugs-CC:</literal> header of the message (no, don't use |
Please send a copy to &email-debian-devel; by using the X-Debbugs-CC |
| 37 |
<literal>CC:</literal>, because that way the message's subject won't indicate |
header (don't use CC:, because that way the message's subject won't |
| 38 |
the bug number). |
indicate the bug number). If you are packaging so many new packages (>10) |
| 39 |
|
that notifying the mailing list in seperate messages is too disruptive, |
| 40 |
|
do send a summary after filing the bugs to the debian-devel list instead. |
| 41 |
|
This will inform the other developers about upcoming packages and will |
| 42 |
|
allow a review of your description and package name. |
| 43 |
</para> |
</para> |
| 44 |
<para> |
<para> |
| 45 |
Please include a <literal>Closes: |
Please include a <literal>Closes: |
| 48 |
package is installed in the archive (see <xref linkend="upload-bugfix"/> ). |
package is installed in the archive (see <xref linkend="upload-bugfix"/> ). |
| 49 |
</para> |
</para> |
| 50 |
<para> |
<para> |
| 51 |
|
If you think your package needs some explanations for the administrators of the |
| 52 |
|
NEW package queue, include them in your changelog, send to ftpmaster@debian.org |
| 53 |
|
a reply to the email you receive as a maintainer after your upload, or reply to |
| 54 |
|
the rejection email in case you are already re-uploading. |
| 55 |
|
</para> |
| 56 |
|
<para> |
| 57 |
When closing security bugs include CVE numbers as well as the Closes: #nnnnn. |
When closing security bugs include CVE numbers as well as the Closes: #nnnnn. |
| 58 |
This is useful for the security team to track vulnerabilities. If an upload is |
This is useful for the security team to track vulnerabilities. If an upload is |
| 59 |
made to fix the bug before the advisory ID is known, it is encouraged to modify |
made to fix the bug before the advisory ID is known, it is encouraged to modify |
| 407 |
|
|
| 408 |
<section id="delayed-incoming"> |
<section id="delayed-incoming"> |
| 409 |
<title>Delayed uploads</title> |
<title>Delayed uploads</title> |
| 410 |
|
|
| 411 |
<para> |
<para> |
| 412 |
Delayed uploads are done for the moment via the delayed queue at <literal>gluck |
It is sometimes useful to upload a package immediately, but to want this |
| 413 |
</literal>. The upload-directory is |
package to arrive in the archive only a few days later. For example, |
| 414 |
<literal>gluck:~tfheen/DELAYED/[012345678]-day</literal>. 0-day is uploaded |
when preparing a <link linkend="nmu">Non-maintainer Upload</link>, |
| 415 |
multiple times per day to <literal>&ftp-master-host;</literal>. |
you might want to give the maintainer a few days to react. |
|
</para> |
|
|
<para> |
|
|
With a fairly recent dput, this section |
|
| 416 |
</para> |
</para> |
| 417 |
<screen> |
|
|
[tfheen_delayed] |
|
|
method = scp |
|
|
fqdn = gluck.debian.org |
|
|
incoming = ~tfheen |
|
|
</screen> |
|
| 418 |
<para> |
<para> |
| 419 |
in <filename>~/.dput.cf</filename> should work fine for uploading to the |
An upload to the delayed directory keeps the package in |
| 420 |
<literal>DELAYED</literal> queue. |
<ulink url="http://ftp-master.debian.org/deferred.html"> |
| 421 |
|
the deferred uploads queue"</ulink>. |
| 422 |
|
When the specified waiting time is over, the package is moved into |
| 423 |
|
the regular incoming directory for processing. |
| 424 |
|
This is done through automatic uploading to |
| 425 |
|
<literal>&ftp-master-host;</literal> in upload-directory |
| 426 |
|
<literal>DELAYED/[012345678]-day</literal>. 0-day is uploaded |
| 427 |
|
multiple times per day to <literal>&ftp-master-host;</literal>. |
| 428 |
</para> |
</para> |
| 429 |
<para> |
<para> |
| 430 |
<emphasis>Note:</emphasis> Since this upload queue goes to |
With dput, you can use the <literal>--delayed <replaceable>DELAY</replaceable></literal> |
| 431 |
<literal>&ftp-master-host;</literal>, the prescription found in <xref |
parameter to put the package into one of the queues. |
|
linkend="upload-ftp-master"/> applies here as well. |
|
| 432 |
</para> |
</para> |
| 433 |
</section> |
</section> |
| 434 |
|
|
| 833 |
fixing them themselves, sending security advisories, and maintaining |
fixing them themselves, sending security advisories, and maintaining |
| 834 |
<literal>security.debian.org</literal>. |
<literal>security.debian.org</literal>. |
| 835 |
</para> |
</para> |
|
<!-- information about the security database goes here once it's ready --> |
|
|
<!-- (mdz) --> |
|
| 836 |
<para> |
<para> |
| 837 |
When you become aware of a security-related bug in a Debian package, whether or |
When you become aware of a security-related bug in a Debian package, whether or |
| 838 |
not you are the maintainer, collect pertinent information about the problem, |
not you are the maintainer, collect pertinent information about the problem, |
| 839 |
and promptly contact the security team at |
and promptly contact the security team at |
| 840 |
&email-security-team; as soon as possible. <emphasis |
&email-security-team; as soon as possible. <emphasis |
| 841 |
role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal>; |
role="strong">DO NOT UPLOAD</emphasis> any packages for <literal>stable</literal> |
| 842 |
the security team will do that. Useful information includes, for example: |
without contacting the team. Useful information includes, for example: |
| 843 |
</para> |
</para> |
| 844 |
<itemizedlist> |
<itemizedlist> |
| 845 |
<listitem> |
<listitem> |
| 874 |
</para> |
</para> |
| 875 |
</listitem> |
</listitem> |
| 876 |
</itemizedlist> |
</itemizedlist> |
| 877 |
|
<para>As the maintainer of the package, you have the responsibility to |
| 878 |
|
maintain it, even in the stable release. You are in the best position |
| 879 |
|
to evaluate patches and test updated packages, so please see the sections |
| 880 |
|
below on how to prepare packages for the Security Team to handle.</para> |
| 881 |
|
|
| 882 |
|
<section id="bug-security-tracker"> |
| 883 |
|
<title>The Security Tracker</title> |
| 884 |
|
<para> |
| 885 |
|
The security team maintains a central database, the |
| 886 |
|
<ulink url="http://security-tracker.debian.net/">Debian Security Tracker</ulink>. |
| 887 |
|
This contains all public information that is known about security issues: |
| 888 |
|
which packages and versions are affected or fixed, and thus whether stable, |
| 889 |
|
testing and/or unstable are vulnerable. Information that is still confidential |
| 890 |
|
is not added to the tracker. |
| 891 |
|
</para> |
| 892 |
|
<para> |
| 893 |
|
You can search it for a specific issue, but also on package name. Look |
| 894 |
|
for your package to see which issues are still open. If you can, please provide |
| 895 |
|
more information about those issues, or help to address them in your package. |
| 896 |
|
Instructions are on the tracker web pages. |
| 897 |
|
</para> |
| 898 |
|
</section> |
| 899 |
|
|
| 900 |
<section id="bug-security-confidentiality"> |
<section id="bug-security-confidentiality"> |
| 901 |
<title>Confidentiality</title> |
<title>Confidentiality</title> |
| 902 |
<para> |
<para> |
| 966 |
requested: the problem has been known for a while, or the problem or exploit |
requested: the problem has been known for a while, or the problem or exploit |
| 967 |
has become public. |
has become public. |
| 968 |
</para> |
</para> |
| 969 |
|
<para> |
| 970 |
|
The Security Team has a PGP-key to enable encrypted communication about |
| 971 |
|
sensitive issues. See the <ulink url="http://www.debian.org/security/faq.en.html#contact">Security Team FAQ</ulink> for details. |
| 972 |
|
</para> |
| 973 |
</section> |
</section> |
| 974 |
|
|
| 975 |
<section id="bug-security-advisories"> |
<section id="bug-security-advisories"> |
| 1106 |
<itemizedlist> |
<itemizedlist> |
| 1107 |
<listitem> |
<listitem> |
| 1108 |
<para> |
<para> |
| 1109 |
Target the right distribution in your <filename>debian/changelog</filename>. |
<emphasis role="strong">Target the right distribution</emphasis> |
| 1110 |
|
in your <filename>debian/changelog</filename>. |
| 1111 |
For <literal>stable</literal> this is <literal>stable-security</literal> and |
For <literal>stable</literal> this is <literal>stable-security</literal> and |
| 1112 |
for testing this is <literal>testing-security</literal>, and for the previous |
for testing this is <literal>testing-security</literal>, and for the previous |
| 1113 |
stable release, this is <literal>oldstable-security</literal>. Do not target |
stable release, this is <literal>oldstable-security</literal>. Do not target |
| 1117 |
</listitem> |
</listitem> |
| 1118 |
<listitem> |
<listitem> |
| 1119 |
<para> |
<para> |
| 1120 |
The upload should have urgency=high. |
The upload should have <emphasis role="strong">urgency=high</emphasis>. |
| 1121 |
</para> |
</para> |
| 1122 |
</listitem> |
</listitem> |
| 1123 |
<listitem> |
<listitem> |
| 1124 |
<para> |
<para> |
| 1125 |
Make descriptive, meaningful changelog entries. Others will rely on them to |
Make descriptive, meaningful changelog entries. Others will rely on them to |
| 1126 |
determine whether a particular bug was fixed. Always include an external |
determine whether a particular bug was fixed. Add <literal>closes:</literal> |
| 1127 |
reference, preferably a CVE identifier, so that it can be cross-referenced. |
statements for any <emphasis role="strong">Debian bugs</emphasis> filed. |
| 1128 |
Include the same information in the changelog for <literal>unstable</literal>, |
Always include an external reference, preferably a <emphasis role="strong">CVE |
| 1129 |
so that it is clear |
identifier</emphasis>, so that it can be cross-referenced. However, if a CVE |
| 1130 |
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 |
| 1131 |
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. |
|
| 1132 |
</para> |
</para> |
| 1133 |
</listitem> |
</listitem> |
| 1134 |
<listitem> |
<listitem> |
| 1135 |
<para> |
<para> |
| 1136 |
Make sure the version number is proper. It must be greater than the current |
Make sure the <emphasis role="strong">version number</emphasis> is proper. |
| 1137 |
package, but less than package versions in later distributions. If in doubt, |
It must be greater than the current package, but less than package versions in |
| 1138 |
test it with <literal>dpkg --compare-versions</literal>. Be careful not to |
later distributions. If in doubt, test it with <literal>dpkg |
| 1139 |
re-use a version number that you have already used for a previous upload. For |
--compare-versions</literal>. Be careful not to re-use a version number that |
| 1140 |
<literal>testing</literal>, there must be a higher version in |
you have already used for a previous upload, or one that conflicts with a |
| 1141 |
<literal>unstable</literal>. If there is none yet (for example, if |
binNMU. The convention is to append |
| 1142 |
<literal>testing</literal> and <literal>unstable</literal> have the same |
<literal>+</literal><replaceable>codename</replaceable><literal>1</literal>, e.g. |
| 1143 |
version) you must upload a new version to <literal>unstable</literal> first. |
<literal>1:2.4.3-4+etch1</literal>, of course increasing 1 for any subsequent |
| 1144 |
</para> |
uploads. |
|
</listitem> |
|
|
<listitem> |
|
|
<para> |
|
|
Do not make source-only uploads if your package has any binary-all packages (do |
|
|
not use the <literal>-S</literal> option to |
|
|
<command>dpkg-buildpackage</command>). The <command>buildd</command> |
|
|
infrastructure will not build those. This point applies to normal package |
|
|
uploads as well. |
|
| 1145 |
</para> |
</para> |
| 1146 |
</listitem> |
</listitem> |
| 1147 |
<listitem> |
<listitem> |
| 1148 |
<para> |
<para> |
| 1149 |
Unless the upstream source has been uploaded to <literal>security.debian.org |
Unless the upstream source has been uploaded to <literal>security.debian.org |
| 1150 |
</literal> before (by a previous security update), build the upload with full |
</literal> before (by a previous security update), build the upload <emphasis |
| 1151 |
upstream source (<literal>dpkg-buildpackage -sa</literal>). If there has been |
role="strong">with full upstream source</emphasis> (<literal>dpkg-buildpackage |
| 1152 |
a previous upload to <literal>security.debian.org</literal> with the same |
-sa</literal>). If there has been a previous upload to |
| 1153 |
upstream version, you may upload without upstream source (<literal> |
<literal>security.debian.org</literal> with the same upstream version, you may |
| 1154 |
dpkg-buildpackage -sd</literal>). |
upload without upstream source (<literal> dpkg-buildpackage -sd</literal>). |
| 1155 |
</para> |
</para> |
| 1156 |
</listitem> |
</listitem> |
| 1157 |
<listitem> |
<listitem> |
| 1158 |
<para> |
<para> |
| 1159 |
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 |
| 1160 |
|
<filename>*.orig.tar.gz</filename></emphasis> as used in the |
| 1161 |
normal archive, otherwise it is not possible to move the security fix into the |
normal archive, otherwise it is not possible to move the security fix into the |
| 1162 |
main archives later. |
main archives later. |
| 1163 |
</para> |
</para> |
| 1164 |
</listitem> |
</listitem> |
| 1165 |
<listitem> |
<listitem> |
| 1166 |
<para> |
<para> |
| 1167 |
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 |
| 1168 |
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 |
| 1169 |
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 |
| 1170 |
setup a chroot (see <xref linkend="pbuilder"/> and <xref |
<xref linkend="server-machines"/> ) or setup a chroot (see |
| 1171 |
linkend="debootstrap"/> ). |
<xref linkend="pbuilder"/> and <xref linkend="debootstrap"/> ). |
| 1172 |
</para> |
</para> |
| 1173 |
</listitem> |
</listitem> |
| 1174 |
</itemizedlist> |
</itemizedlist> |
| 1201 |
</para> |
</para> |
| 1202 |
<para> |
<para> |
| 1203 |
Once an upload to the security queue has been accepted, the package will |
Once an upload to the security queue has been accepted, the package will |
| 1204 |
automatically be rebuilt for all architectures and stored for verification by |
automatically be built for all architectures and stored for verification by |
| 1205 |
the security team. |
the security team. |
| 1206 |
</para> |
</para> |
| 1207 |
<para> |
<para> |
| 1790 |
The buildds admins of each arch can be contacted at the mail address |
The buildds admins of each arch can be contacted at the mail address |
| 1791 |
<literal><replaceable>arch</replaceable>@buildd.debian.org</literal>. |
<literal><replaceable>arch</replaceable>@buildd.debian.org</literal>. |
| 1792 |
</para> |
</para> |
| 1793 |
|
|
| 1794 |
|
<para> |
| 1795 |
|
Since the Release team also has access to wanna-build, |
| 1796 |
|
it has become common practice to ask them to perform actions such as |
| 1797 |
|
the recompilation of packages (binNMUs, see <xref linkend="binary-only-nmu"/>) |
| 1798 |
|
or the retry of failed builds (give-backs). |
| 1799 |
|
The format to use when requesting such actions is described at |
| 1800 |
|
<ulink url="&url-release-wb;"/>. |
| 1801 |
|
</para> |
| 1802 |
|
|
| 1803 |
</section> |
</section> |
| 1804 |
|
|
| 1805 |
</section> |
</section> |
| 1861 |
<section id="nmu"> |
<section id="nmu"> |
| 1862 |
<title>Non-Maintainer Uploads (NMUs)</title> |
<title>Non-Maintainer Uploads (NMUs)</title> |
| 1863 |
<para> |
<para> |
| 1864 |
Under certain circumstances it is necessary for someone other than the official |
Every package has one or more maintainers. Normally, these are the people who |
| 1865 |
package maintainer to make a release of a package. This is called a |
work on and upload new versions of the package. In some situations, it is |
| 1866 |
non-maintainer upload, or NMU. |
useful that other developers can upload a new version as well, for example if |
| 1867 |
</para> |
they want to fix a bug in a package they don't maintain, when the maintainer |
| 1868 |
<para> |
needs help to respond to issues. Such uploads are called |
| 1869 |
This section handles only source NMUs, i.e. NMUs which upload a new version of |
<emphasis>Non-Maintainer Uploads (NMU)</emphasis>. |
|
the package. For binary-only NMUs by porters or QA members, please see <xref |
|
|
linkend="binary-only-nmu"/> . If a buildd builds and uploads a package, that |
|
|
too is strictly speaking a binary NMU. See <xref linkend="wanna-build"/> for |
|
|
some more information. |
|
|
</para> |
|
|
<para> |
|
|
The main reason why NMUs are done is when a developer needs to fix another |
|
|
developer's package in order to address serious problems or crippling bugs or |
|
|
when the package maintainer is unable to release a fix in a timely fashion. |
|
|
</para> |
|
|
<para> |
|
|
First and foremost, it is critical that NMU patches to source should be as |
|
|
non-disruptive as possible. Do not do housekeeping tasks, do not change the |
|
|
name of modules or files, do not move directories; in general, do not fix |
|
|
things which are not broken. Keep the patch as small as possible. If things |
|
|
bother you aesthetically, talk to the Debian maintainer, talk to the upstream |
|
|
maintainer, or submit a bug. However, aesthetic changes must |
|
|
<emphasis>not</emphasis> be made in a non-maintainer upload. |
|
|
</para> |
|
|
<para> |
|
|
And please remember the Hippocratic Oath: Above all, do no harm. It is better |
|
|
to leave a package with an open grave bug than applying a non-functional patch, |
|
|
or one that hides the bug instead of resolving it. |
|
| 1870 |
</para> |
</para> |
| 1871 |
|
|
| 1872 |
<section id="nmu-guidelines"> |
<section id="nmu-guidelines"> |
| 1873 |
<title>How to do a NMU</title> |
<title>When and how to do an NMU</title> |
| 1874 |
<para> |
|
|
NMUs which fix important, serious or higher severity bugs are encouraged and |
|
|
accepted. You should endeavor to reach the current maintainer of the package; |
|
|
they might be just about to upload a fix for the problem, or have a better |
|
|
solution. |
|
|
</para> |
|
|
<para> |
|
|
NMUs should be made to assist a package's maintainer in resolving bugs. |
|
|
Maintainers should be thankful for that help, and NMUers should respect the |
|
|
decisions of maintainers, and try to personally help the maintainer by their |
|
|
work. |
|
|
</para> |
|
| 1875 |
<para> |
<para> |
| 1876 |
A NMU should follow all conventions, written down in this section. For an |
Before doing an NMU, consider the following questions: |
|
upload to <literal>testing</literal> or <literal>unstable</literal>, this |
|
|
order of steps is recommended: |
|
| 1877 |
</para> |
</para> |
| 1878 |
<itemizedlist> |
<itemizedlist> |
| 1879 |
<listitem> |
<listitem> |
| 1880 |
<para> |
<para> |
| 1881 |
Make sure that the package's bugs that the NMU is meant to address are all |
Does your NMU really fix bugs? Fixing cosmetic issues or changing the |
| 1882 |
filed in the Debian Bug Tracking System (BTS). If they are not, submit them |
packaging style in NMUs is discouraged. |
|
immediately. |
|
| 1883 |
</para> |
</para> |
| 1884 |
</listitem> |
</listitem> |
| 1885 |
<listitem> |
<listitem> |
| 1886 |
<para> |
<para> |
| 1887 |
Wait a few days for the response from the maintainer. If you don't get any |
Did you give enough time to the maintainer? When was the bug reported to the |
| 1888 |
response, you may want to help them by sending the patch that fixes the bug. |
BTS? Being busy for a week or two isn't unusual. Is the bug so severe that it |
| 1889 |
Don't forget to tag the bug with the patch keyword. |
needs to be fixed right now, or can it wait a few more days? |
| 1890 |
</para> |
</para> |
| 1891 |
</listitem> |
</listitem> |
| 1892 |
<listitem> |
<listitem> |
| 1893 |
<para> |
<para> |
| 1894 |
Wait a few more days. If you still haven't got an answer from the maintainer, |
How confident are you about your changes? Please remember the Hippocratic Oath: |
| 1895 |
send them a mail announcing your intent to NMU the package. Prepare an NMU as |
"Above all, do no harm." It is better to leave a package with an open grave bug |
| 1896 |
described in this section, and test it carefully on your machine (cf. <xref |
than applying a non-functional patch, or one that hides the bug instead of |
| 1897 |
linkend="sanitycheck"/> ). Double check that your patch doesn't have any |
resolving it. If you are not 100% sure of what you did, it might be a good idea |
| 1898 |
unexpected side effects. Make sure your patch is as small and as |
to seek advice from others. Remember that if you break something in your NMU, |
| 1899 |
non-disruptive as it can be. |
many people will be very unhappy about it. |
| 1900 |
</para> |
</para> |
| 1901 |
</listitem> |
</listitem> |
| 1902 |
<listitem> |
<listitem> |
| 1903 |
<para> |
<para> |
| 1904 |
Upload your package to incoming in <filename>DELAYED/7-day</filename> (cf. |
Have you clearly expressed your intention to NMU, at least in the BTS? |
| 1905 |
<xref linkend="delayed-incoming"/> ), send the final patch to the maintainer |
It is also a good idea to try to contact the |
| 1906 |
via the BTS, and explain to them that they have 7 days to react if they want to |
maintainer by other means (private email, IRC). |
|
cancel the NMU. |
|
| 1907 |
</para> |
</para> |
| 1908 |
</listitem> |
</listitem> |
| 1909 |
<listitem> |
<listitem> |
| 1910 |
<para> |
<para> |
| 1911 |
Follow what happens, you're responsible for any bug that you introduced with |
If the maintainer is usually active and responsive, have you tried to contact |
| 1912 |
your NMU. You should probably use <xref linkend="pkg-tracking-system"/> (PTS) |
him? In general it should be considered preferable that a maintainer takes care |
| 1913 |
to stay informed of the state of the package after your NMU. |
of an issue himself and that he is given the chance to review and correct your |
| 1914 |
|
patch, because he can be expected to be more aware of potential issues which an |
| 1915 |
|
NMUer might miss. It is often a better use of everyone's time if the maintainer |
| 1916 |
|
is given an opportunity to upload a fix on their own. |
| 1917 |
</para> |
</para> |
| 1918 |
</listitem> |
</listitem> |
| 1919 |
</itemizedlist> |
</itemizedlist> |
| 1920 |
<para> |
<para> |
| 1921 |
At times, the release manager or an organized group of developers can announce |
When doing an NMU, you must first make sure that your intention to NMU is |
| 1922 |
a certain period of time in which the NMU rules are relaxed. This usually |
clear. Then, you must send a patch with the differences between the |
| 1923 |
involves shortening the period during which one is to wait before uploading the |
current package and your proposed NMU to the BTS. The |
| 1924 |
fixes, and shortening the DELAYED period. It is important to notice that even |
<literal>nmudiff</literal> script in the <literal>devscripts</literal> package |
| 1925 |
in these so-called bug squashing party times, the NMU'er has to file bugs and |
might be helpful. |
| 1926 |
contact the developer first, and act later. Please see <xref |
</para> |
| 1927 |
linkend="qa-bsp"/> for details. |
<para> |
| 1928 |
</para> |
While preparing the patch, you should better be aware of any package-specific |
| 1929 |
<para> |
practices that the maintainer might be using. Taking them into account reduces |
| 1930 |
For the <literal>testing</literal> distribution, the rules may be changed by |
the burden of getting your changes integrated back in the normal package |
| 1931 |
the release managers. Please take additional care, and acknowledge that the |
workflow and thus increases the possibilities that that will happen. A good |
| 1932 |
usual way for a package to enter <literal>testing</literal> is through |
place where to look for for possible package-specific practices is |
| 1933 |
<literal>unstable</literal>. |
<ulink url="&url-debian-policy;ch-source.html#s-readmesource"><literal>debian/README.source</literal></ulink>. |
| 1934 |
</para> |
</para> |
| 1935 |
<para> |
<para> |
| 1936 |
For the stable distribution, please take extra care. Of course, the release |
Unless you have an excellent reason not to do so, you must then give some time |
| 1937 |
managers may also change the rules here. Please verify before you upload that |
to the maintainer to react (for example, by uploading to the |
| 1938 |
all your changes are OK for inclusion into the next stable release by the |
<literal>DELAYED</literal> queue). Here are some recommended values to use for delays: |
|
release manager. |
|
| 1939 |
</para> |
</para> |
| 1940 |
|
<itemizedlist> |
| 1941 |
|
<listitem> |
| 1942 |
<para> |
<para> |
| 1943 |
When a security bug is detected, the security team may do an NMU, using their |
Upload fixing only release-critical bugs older than 7 days: 2 days |
|
own rules. Please refer to <xref linkend="bug-security"/> for more |
|
|
information. |
|
| 1944 |
</para> |
</para> |
| 1945 |
|
</listitem> |
| 1946 |
|
<listitem> |
| 1947 |
<para> |
<para> |
| 1948 |
For the differences for Porters NMUs, please see <xref |
Upload fixing only release-critical and important bugs: 5 days |
|
linkend="source-nmu-when-porter"/> . |
|
| 1949 |
</para> |
</para> |
| 1950 |
|
</listitem> |
| 1951 |
|
<listitem> |
| 1952 |
<para> |
<para> |
| 1953 |
Of course, it is always possible to agree on special rules with a maintainer |
Other NMUs: 10 days |
|
(like the maintainer asking please upload this fix directly for me, and no diff |
|
|
required). |
|
| 1954 |
</para> |
</para> |
| 1955 |
</section> |
</listitem> |
| 1956 |
|
</itemizedlist> |
| 1957 |
|
|
|
<section id="nmu-version"> |
|
|
<title>NMU version numbering</title> |
|
|
<para> |
|
|
Whenever you have made a change to a package, no matter how trivial, the |
|
|
version number needs to change. This enables our packing system to function. |
|
|
</para> |
|
| 1958 |
<para> |
<para> |
| 1959 |
If you are doing a non-maintainer upload (NMU), you should add a new minor |
Those delays are only examples. In some cases, such as uploads fixing security |
| 1960 |
version number to the <replaceable>debian-revision</replaceable> part of the |
issues, or fixes for trivial bugs that blocking a transition, it is desirable |
| 1961 |
version number (the portion after the last hyphen). This extra minor number |
that the fixed package reaches <literal>unstable</literal> sooner. |
|
will start at `1'. For example, consider the package `foo', which is at |
|
|
version 1.1-3. In the archive, the source package control file would be |
|
|
<filename>foo_1.1-3.dsc</filename>. The upstream version is `1.1' and the |
|
|
Debian revision is `3'. The next NMU would add a new minor number `.1' to the |
|
|
Debian revision; the new source control file would be |
|
|
<filename>foo_1.1-3.1.dsc</filename>. |
|
| 1962 |
</para> |
</para> |
| 1963 |
|
|
| 1964 |
<para> |
<para> |
| 1965 |
The Debian revision minor number is needed to avoid stealing one of the package |
Sometimes, release managers decide to allow NMUs with shorter delays for a |
| 1966 |
maintainer's version numbers, which might disrupt their work. It also has the |
subset of bugs (e.g release-critical bugs older than 7 days). Also, some |
| 1967 |
benefit of making it visually clear that a package in the archive was not made |
maintainers list themselves in the <ulink url="&url-low-threshold-nmu;">Low |
| 1968 |
by the official maintainer. |
Threshold NMU list</ulink>, and accept that NMUs are uploaded without delay. But |
| 1969 |
|
even in those cases, it's still a good idea to give the maintainer a few days |
| 1970 |
|
to react before you upload, especially if the patch wasn't available in the BTS |
| 1971 |
|
before, or if you know that the maintainer is generally active. |
| 1972 |
</para> |
</para> |
| 1973 |
|
|
| 1974 |
<para> |
<para> |
| 1975 |
If there is no <replaceable>debian-revision</replaceable> component in the |
After you upload an NMU, you are responsible for the possible problems that you |
| 1976 |
version number then one should be created, starting at `0.1' (but in case of a |
might have introduced. You must keep an eye on the package (subscribing to the |
| 1977 |
debian native package still upload it as native package). If it is absolutely |
package on the PTS is a good way to achieve this). |
|
necessary for someone other than the usual maintainer to make a release based |
|
|
on a new upstream version then the person making the release should start with |
|
|
the <replaceable>debian-revision</replaceable> value `0.1'. The usual |
|
|
maintainer of a package should start their |
|
|
<replaceable>debian-revision</replaceable> numbering at `1'. |
|
| 1978 |
</para> |
</para> |
| 1979 |
|
|
| 1980 |
<para> |
<para> |
| 1981 |
If you upload a package to <literal>testing</literal> or <literal>stable |
This is not a license to perform NMUs thoughtlessly. If you NMU when it is |
| 1982 |
</literal>, sometimes, you need to fork the version number tree. For this, |
clear that the maintainers are active and would have acknowledged a patch in a |
| 1983 |
version numbers like 1.1-3sarge0.1 could be used. |
timely manner, or if you ignore the recommendations of this document, your |
| 1984 |
|
upload might be a cause of conflict with the maintainer. |
| 1985 |
|
You should always be prepared to |
| 1986 |
|
defend the wisdom of any NMU you perform on its own merits. |
| 1987 |
</para> |
</para> |
| 1988 |
</section> |
</section> |
| 1989 |
|
|
| 1990 |
<section id="nmu-changelog"> |
<section id="nmu-changelog"> |
| 1991 |
<title>Source NMUs must have a new changelog entry</title> |
<title>NMUs and debian/changelog</title> |
| 1992 |
<para> |
<para> |
| 1993 |
Anyone who is doing a source NMU must create a changelog entry, describing |
Just like any other (source) upload, NMUs must add an entry to |
| 1994 |
which bugs are fixed by the NMU, and generally why the NMU was required and |
<literal>debian/changelog</literal>, telling what has changed with this |
| 1995 |
what it fixed. The changelog entry will have the email address of the person |
upload. The first line of this entry must explicitely mention that this upload is an NMU, e.g.: |
|
who uploaded it in the log entry and the NMU version number in it. |
|
|
</para> |
|
|
<para> |
|
|
By convention, source NMU changelog entries start with the line |
|
| 1996 |
</para> |
</para> |
| 1997 |
<screen> |
<screen> |
| 1998 |
* Non-maintainer upload |
* Non-maintainer upload. |
| 1999 |
</screen> |
</screen> |
|
</section> |
|
| 2000 |
|
|
|
<section id="nmu-patch"> |
|
|
<title>Source NMUs and the Bug Tracking System</title> |
|
| 2001 |
<para> |
<para> |
| 2002 |
Maintainers other than the official package maintainer should make as few |
The way to version NMUs differs for native and non-native packages. |
|
changes to the package as possible, and they should always send a patch as a |
|
|
unified context diff (<literal>diff -u</literal>) detailing their changes to |
|
|
the Bug Tracking System. |
|
| 2003 |
</para> |
</para> |
| 2004 |
<para> |
<para> |
| 2005 |
What if you are simply recompiling the package? If you just need to recompile |
If the package is a native package (without a debian revision in the version number), |
| 2006 |
it for a single architecture, then you may do a binary-only NMU as described in |
the version must be the version of the last maintainer upload, plus |
| 2007 |
<xref linkend="binary-only-nmu"/> which doesn't require any patch to be sent. |
<literal>+nmu<replaceable>X</replaceable></literal>, where |
| 2008 |
If you want the package to be recompiled for all architectures, then you do a |
<replaceable>X</replaceable> is a counter starting at <literal>1</literal>. |
| 2009 |
source NMU as usual and you will have to send a patch. |
If |
| 2010 |
|
the last upload was also an NMU, the counter should be increased. For example, |
| 2011 |
|
if the current version is <literal>1.5</literal>, then an NMU would get |
| 2012 |
|
version <literal>1.5+nmu1</literal>. |
| 2013 |
|
</para> |
| 2014 |
|
<para> |
| 2015 |
|
If the package is a not a native package, you should add a minor version number |
| 2016 |
|
to the debian revision part of the version number (the portion after the last |
| 2017 |
|
hyphen). This extra number must start at 1. For example, |
| 2018 |
|
if the current version is <literal>1.5-2</literal>, then an NMU would get |
| 2019 |
|
version <literal>1.5-2.1</literal>. If a new upstream version |
| 2020 |
|
is packaged in the NMU, the debian revision is set to <literal>0</literal>, for |
| 2021 |
|
example <literal>1.6-0.1</literal>. |
| 2022 |
|
</para> |
| 2023 |
|
<para> |
| 2024 |
|
In both cases, if the last upload was also an NMU, the counter should |
| 2025 |
|
be increased. For example, if the current version is |
| 2026 |
|
<literal>1.5+nmu3</literal> (a native package which has already been |
| 2027 |
|
NMUed), the NMU would get version <literal>1.5+nmu4</literal>. . |
| 2028 |
|
</para> |
| 2029 |
|
<para> |
| 2030 |
|
A special versioning scheme is needed to avoid disrupting the maintainer's |
| 2031 |
|
work, since using an integer for the Debian revision will potentially |
| 2032 |
|
conflict with a maintainer upload already in preparation at the time of an |
| 2033 |
|
NMU, or even one sitting in the ftp NEW queue. |
| 2034 |
|
It also has the |
| 2035 |
|
benefit of making it visually clear that a package in the archive was not made |
| 2036 |
|
by the official maintainer. |
| 2037 |
|
</para> |
| 2038 |
|
|
| 2039 |
|
<para> |
| 2040 |
|
If you upload a package to testing or stable, you sometimes need to "fork" the |
| 2041 |
|
version number tree. This is the case for security uploads, for example. For |
| 2042 |
|
this, a version of the form |
| 2043 |
|
<literal>+deb<replaceable>XY</replaceable>u<replaceable>Z</replaceable></literal> |
| 2044 |
|
should be used, where <replaceable>X</replaceable> and |
| 2045 |
|
<replaceable>Y</replaceable> are the major and minor release numbers, and |
| 2046 |
|
<replaceable>Z</replaceable> is a counter starting at <literal>1</literal>. |
| 2047 |
|
When the release number is not yet known (often the case for |
| 2048 |
|
<literal>testing</literal>, at the beginning of release cycles), the lowest |
| 2049 |
|
release number higher than the last stable release number must be used. For |
| 2050 |
|
example, while Etch (Debian 4.0) is stable, a security NMU to stable for a |
| 2051 |
|
package at version <literal>1.5-3</literal> would have version |
| 2052 |
|
<literal>1.5-3+deb40u1</literal>, whereas a security NMU to Lenny would get |
| 2053 |
|
version <literal>1.5-3+deb50u1</literal>. After the release of Lenny, security |
| 2054 |
|
uploads to the <literal>testing</literal> distribution will be versioned |
| 2055 |
|
<literal>+deb51uZ</literal>, until it is known whether that release will be |
| 2056 |
|
Debian 5.1 or Debian 6.0 (if that becomes the case, uploads will be versioned |
| 2057 |
|
as <literal>+deb60uZ</literal>. |
| 2058 |
</para> |
</para> |
| 2059 |
|
</section> |
| 2060 |
|
|
| 2061 |
|
<section id="nmu-delayed"> |
| 2062 |
|
<title>Using the <literal>DELAYED/</literal> queue</title> |
| 2063 |
|
|
| 2064 |
<para> |
<para> |
| 2065 |
Bugs fixed by source NMUs used to be tagged fixed instead of closed, but since |
Having to wait for a response after you request permission to NMU is |
| 2066 |
version tracking is in place, such bugs are now also closed with the NMU |
inefficient, because it costs the NMUer a context switch to come back to the |
| 2067 |
version. |
issue. |
| 2068 |
|
The <literal>DELAYED</literal> queue (see <xref linkend="delayed-incoming"/>) |
| 2069 |
|
allows the developer doing the NMU to perform all the necessary tasks at the |
| 2070 |
|
same time. For instance, instead of telling the maintainer that you will |
| 2071 |
|
upload the updated |
| 2072 |
|
package in 7 days, you should upload the package to |
| 2073 |
|
<literal>DELAYED/7</literal> and tell the maintainer that he has 7 days to |
| 2074 |
|
react. During this time, the maintainer can ask you to delay the upload some |
| 2075 |
|
more, or cancel your upload. |
| 2076 |
</para> |
</para> |
| 2077 |
|
|
| 2078 |
<para> |
<para> |
| 2079 |
Also, after doing an NMU, you have to send the information to the existing bugs |
The <literal>DELAYED</literal> queue should not be used to put additional |
| 2080 |
that are fixed by your NMU, including the unified diff. Historically, it was |
pressure on the maintainer. In particular, it's important that you are |
| 2081 |
custom to open a new bug and include a patch showing all the changes you have |
available to cancel or delay the upload before the delay expires since the |
| 2082 |
made. The normal maintainer will either apply the patch or employ an alternate |
maintainer cannot cancel the upload himself. |
|
method of fixing the problem. Sometimes bugs are fixed independently upstream, |
|
|
which is another good reason to back out an NMU's patch. If the maintainer |
|
|
decides not to apply the NMU's patch but to release a new version, the |
|
|
maintainer needs to ensure that the new upstream version really fixes each |
|
|
problem that was fixed in the non-maintainer release. |
|
| 2083 |
</para> |
</para> |
| 2084 |
|
|
| 2085 |
<para> |
<para> |
| 2086 |
In addition, the normal maintainer should <emphasis>always</emphasis> retain |
If you make an NMU to <literal>DELAYED</literal> and the maintainer updates |
| 2087 |
the entry in the changelog file documenting the non-maintainer upload -- and of |
his package before the delay expires, your upload will be rejected because a |
| 2088 |
course, also keep the changes. If you revert some of the changes, please |
newer version is already available in the archive. |
| 2089 |
reopen the relevant bug reports. |
Ideally, the maintainer will take care to include your proposed changes (or |
| 2090 |
|
at least a solution for the problems they address) in that upload. |
| 2091 |
</para> |
</para> |
| 2092 |
|
|
| 2093 |
</section> |
</section> |
| 2094 |
|
|
| 2095 |
<section id="nmu-build"> |
<section id="nmu-maintainer"> |
| 2096 |
<title>Building source NMUs</title> |
<title>NMUs from the maintainer's point of view</title> |
| 2097 |
|
|
| 2098 |
<para> |
<para> |
| 2099 |
Source NMU packages are built normally. Pick a distribution using the same |
When someone NMUs your package, this means they want to help you to keep it in |
| 2100 |
rules as found in <xref linkend="distribution"/> , follow the other |
good shape. This gives users fixed packages faster. You |
| 2101 |
instructions in <xref linkend="upload"/> . |
can consider asking the NMUer to become a co-maintainer of the package. |
| 2102 |
|
Receiving an NMU on a package is not a bad |
| 2103 |
|
thing; it just means that the package is interesting enough for other people to |
| 2104 |
|
work on it. |
| 2105 |
</para> |
</para> |
| 2106 |
|
|
| 2107 |
<para> |
<para> |
| 2108 |
Make sure you do <emphasis>not</emphasis> change the value of the maintainer in |
To acknowledge an NMU, include its changes and changelog entry in your next |
| 2109 |
the <filename>debian/control</filename> file. Your name as given in the NMU |
maintainer upload. If you do not acknowledge the NMU by including the |
| 2110 |
entry of the <filename>debian/changelog</filename> file will be used for |
NMU changelog entry in your changelog, the bugs will remain closed in the |
| 2111 |
signing the changes file. |
BTS but will be listed as affecting your maintainer version of the package. |
| 2112 |
</para> |
</para> |
| 2113 |
|
|
| 2114 |
</section> |
</section> |
| 2115 |
|
|
| 2116 |
<section id="ack-nmu"> |
<section id="nmu-binnmu"> |
| 2117 |
<title>Acknowledging an NMU</title> |
<title>Source NMUs vs Binary-only NMUs (binNMUs)</title> |
| 2118 |
|
|
| 2119 |
<para> |
<para> |
| 2120 |
If one of your packages has been NMU'ed, you have to incorporate the changes in |
The full name of an NMU is <emphasis>source NMU</emphasis>. There is also |
| 2121 |
your copy of the sources. This is easy, you just have to apply the patch that |
another type, namely the <emphasis>binary-only NMU</emphasis>, or |
| 2122 |
has been sent to you. Once this is done, you have to close the bugs that have |
<emphasis>binNMU</emphasis>. A binNMU is also a package upload by someone |
| 2123 |
been tagged fixed by the NMU. The easiest way is to use the |
other than the package's maintainer. However, it is a binary-only upload. |
|
<literal>-v</literal> option of <command>dpkg-buildpackage</command>, as this |
|
|
allows you to include just all changes since your last maintainer upload. |
|
|
Alternatively, you can close them manually by sending the required mails to the |
|
|
BTS or by adding the required <literal>closes: #nnnn</literal> in the changelog |
|
|
entry of your next upload. |
|
| 2124 |
</para> |
</para> |
| 2125 |
|
|
| 2126 |
<para> |
<para> |
| 2127 |
In any case, you should not be upset by the NMU. An NMU is not a personal |
When a library (or other dependency) is updated, the packages using it may need |
| 2128 |
attack against the maintainer. It is a proof that someone cares enough about |
to be rebuilt. Since no changes to the source are needed, the same source |
| 2129 |
the package that they were willing to help you in your work, so you should be |
package is used. |
|
thankful. You may also want to ask them if they would be interested in helping |
|
|
you on a more frequent basis as co-maintainer or backup maintainer (see <xref |
|
|
linkend="collaborative-maint"/> ). |
|
| 2130 |
</para> |
</para> |
|
</section> |
|
| 2131 |
|
|
|
<section id="nmu-vs-qa"> |
|
|
<title>NMU vs QA uploads</title> |
|
| 2132 |
<para> |
<para> |
| 2133 |
Unless you know the maintainer is still active, it is wise to check the package |
BinNMUs are usually triggered on the buildds by wanna-build. |
| 2134 |
to see if it has been orphaned. The current list of orphaned packages which |
An entry is added to debian/changelog, |
| 2135 |
haven't had their maintainer set correctly is available at <ulink |
explaining why the upload was needed and increasing the version number as |
| 2136 |
url="&url-debian-qa-orphaned;"></ulink>. If you perform an NMU on an |
described in <xref linkend="binary-only-nmu"/>. |
| 2137 |
improperly orphaned package, please set the maintainer to <literal>Debian QA Group |
This entry should not be included in the next upload. |
|
<packages@qa.debian.org></literal>. |
|
| 2138 |
</para> |
</para> |
|
</section> |
|
| 2139 |
|
|
|
<section id="nmu-who"> |
|
|
<title>Who can do an NMU</title> |
|
| 2140 |
<para> |
<para> |
| 2141 |
Only official, registered Debian Developers can do binary or source NMUs. A |
Buildds upload packages for their architecture to the archive as binary-only |
| 2142 |
Debian Developer is someone who has their key in the Debian key ring. |
uploads. Strictly speaking, these are binNMUs. However, they are not normally |
| 2143 |
Non-developers, however, are encouraged to download the source package and |
called NMU, and they don't add an entry to debian/changelog. |
|
start hacking on it to fix problems; however, rather than doing an NMU, they |
|
|
should just submit worthwhile patches to the Bug Tracking System. Maintainers |
|
|
almost always appreciate quality patches and bug reports. |
|
| 2144 |
</para> |
</para> |
| 2145 |
|
|
| 2146 |
</section> |
</section> |
| 2147 |
|
|
| 2148 |
<section id="nmu-terms"> |
<section id="nmu-qa-upload"> |
| 2149 |
<title>Terminology</title> |
<title>NMUs vs QA uploads</title> |
| 2150 |
|
|
| 2151 |
<para> |
<para> |
| 2152 |
There are two new terms used throughout this section: ``binary-only NMU'' and |
NMUs are uploads of packages by somebody else than their assigned maintainer. |
| 2153 |
``source NMU''. These terms are used with specific technical meaning |
There is |
| 2154 |
throughout this document. Both binary-only and source NMUs are similar, since |
another type of upload where the uploaded package is not yours: QA uploads. QA |
| 2155 |
they involve an upload of a package by a developer who is not the official |
uploads are uploads of orphaned packages. |
|
maintainer of that package. That is why it's a |
|
|
<literal>non-maintainer</literal> upload. |
|
| 2156 |
</para> |
</para> |
| 2157 |
|
|
| 2158 |
<para> |
<para> |
| 2159 |
A source NMU is an upload of a package by a developer who is not the official |
QA uploads are very much like normal maintainer uploads: they may fix anything, |
| 2160 |
maintainer, for the purposes of fixing a bug in the package. Source NMUs |
even minor issues; the version numbering is normal, and there is no need to use |
| 2161 |
always involves changes to the source (even if it is just a change to |
a delayed upload. The difference is that you are not listed as the Maintainer |
| 2162 |
<filename>debian/changelog</filename>). This can be either a change to the |
or Uploader for the package. Also, the changelog entry of a QA upload has a |
| 2163 |
upstream source, or a change to the Debian bits of the source. Note, however, |
special first line: |
|
that source NMUs may also include architecture-dependent packages, as well as |
|
|
an updated Debian diff. |
|
| 2164 |
</para> |
</para> |
| 2165 |
|
|
| 2166 |
|
<screen> |
| 2167 |
|
* QA upload. |
| 2168 |
|
</screen> |
| 2169 |
|
|
| 2170 |
<para> |
<para> |
| 2171 |
A binary-only NMU is a recompilation and upload of a binary package for a given |
If you want to do an NMU, and it seems that the maintainer is not active, it is |
| 2172 |
architecture. As such, it is usually part of a porting effort. A binary-only |
wise to check if the package is orphaned |
| 2173 |
NMU is a non-maintainer uploaded binary version of a package, with no source |
(this information is displayed on the package's Package Tracking System page). |
| 2174 |
changes required. There are many cases where porters must fix problems in the |
When doing the first QA upload to an |
| 2175 |
source in order to get them to compile for their target architecture; that |
orphaned package, the maintainer should be set to <literal>Debian QA Group |
| 2176 |
would be considered a source NMU rather than a binary-only NMU. As you can |
<packages@qa.debian.org></literal>. Orphaned packages which did |
| 2177 |
see, we don't distinguish in terminology between porter NMUs and non-porter |
not yet have a QA upload still have their old maintainer set. There is a list |
| 2178 |
NMUs. |
of them at <ulink url="&url-orphaned-not-qa;"/>. |
| 2179 |
</para> |
</para> |
| 2180 |
|
|
| 2181 |
<para> |
<para> |
| 2182 |
Both classes of NMUs, source and binary-only, can be lumped under the term |
Instead of doing a QA upload, you can also consider adopting the package by |
| 2183 |
``NMU''. However, this often leads to confusion, since most people think |
making yourself the maintainer. You don't need permission from anybody to |
| 2184 |
``source NMU'' when they think ``NMU''. So it's best to be careful: always use |
adopt an orphaned package, you can just set yourself as maintainer and upload |
| 2185 |
``binary NMU'' or ``binNMU'' for binary-only NMUs. |
the new version (see <xref linkend="adopting"/>). |
| 2186 |
</para> |
</para> |
| 2187 |
|
|
| 2188 |
</section> |
</section> |
| 2189 |
|
|
| 2190 |
</section> |
</section> |
| 2322 |
<listitem> |
<listitem> |
| 2323 |
<para> |
<para> |
| 2324 |
It must be available on all architectures on which it has previously been built |
It must be available on all architectures on which it has previously been built |
| 2325 |
in <literal>unstable</literal>. <xref linkend="dak ls"/> may be of interest |
in <literal>unstable</literal>. <xref linkend="dak-ls"/> may be of interest |
| 2326 |
to check that information; |
to check that information; |
| 2327 |
</para> |
</para> |
| 2328 |
</listitem> |
</listitem> |
Parent Directory
| 
Revision Log
| 
Patch