X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=8698e292cf5c22047500915027370c8cfb5b9660;hb=44e618bcf365a9652306644907b9e167a39c13b7;hp=95f5bc35f33b2e9689aa592fdbde4b46a412ac26;hpb=b371924c48cc2132db092d34c6c853d55f411f0c;p=developers-reference.git
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 95f5bc3..8698e29 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -7,7 +7,7 @@
%dynamicdata;
-
+
@@ -58,6 +58,7 @@ writing to the &fsf-addr;.
If you want to print this reference, you should use the .
+This page is also available in .
]]>
@@ -309,13 +310,12 @@ can update the Debian key ring by sending your key to the key server at
&keyserver-host;.
If you need to add a completely new key or remove an old key, you need
-to get the new key signed by another developer. After this, a mail
-signed by another developer listing your account name, the keyids
-of the old and of the new key and the reason should be send to
-&email-debian-keyring;. If the old key is compromised or invalid, you
+to get the new key signed by another developer.
+If the old key is compromised or invalid, you
also have to add the revocation certificate. If there is no real
-reason for a new key, the Keyring Maintainers will only accept it if
-it's more secure and connected to the old key.
+reason for a new key, the Keyring Maintainers might reject the new key.
+Details can be found at
+.
The same key extraction routines discussed in [
apply.
@@ -669,17 +669,10 @@ an email to &email-ftpmaster;, but also see the procedures in
The non-US server
]
-The non-US server, non-us.debian.org,
-holds the canonical copy of the non-US part of the Debian archive.
-If you need to upload a package into one of the non-US sections, upload it
-to this server; see [.
- ]
-Problems with the non-US package archive should generally be submitted as
-bugs against the nonus.debian.org pseudo-package (notice
-the lack of hyphen between "non" and "us" in the pseudo-package name
-— that's for backwards compatibility). Remember to check whether or
-not someone else has already reported the problem to the
-.
+The non-US server non-us.debian.org
+was discontinued with the release of sarge. The pseudo-package
+nonus.debian.org
+stil exists for now.
The www-master server
@@ -710,8 +703,7 @@ whereas on other hosts it won't.
Usually the only reason to use a different host is when you need to publish
materials subject to the U.S. export restrictions, in which case you can use
-one of the other servers located outside the United States, such as the
-aforementioned non-us.debian.org.
+one of the other servers located outside the United States.
Send mail to &email-debian-devel; if you have any questions.
@@ -996,7 +988,7 @@ stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
so forth).
Please refer to
-uploads to the stable distribution
+uploads to the stable distribution
for details.
Note that development under unstable continues during the
@@ -1131,8 +1123,7 @@ have accounts on these machines.
The Incoming system is responsible for collecting updated packages and
installing them in the Debian archive. It consists of a set of
-directories and scripts that are installed both on &ftp-master-host;
-and &non-us-host;.
+directories and scripts that are installed on &ftp-master-host;.
Packages are uploaded by all the maintainers into a directory called
UploadQueue.
@@ -1251,7 +1242,7 @@ You can view the bugs of a given package at the URL
The madison utility
madison is a command-line utility that is available
-on both &ftp-master-host; and &non-us-host;, and on
+on &ftp-master-host;, and on
the mirror on &ftp-master-mirror;. It
uses a single argument corresponding to a package name. In result
it displays which version of the package is available for each
@@ -1543,8 +1534,23 @@ by Debian, facilitate contributions from external developers to projects
started by Debian, and help projects whose goals are the promotion of Debian
or its derivatives.
+All Debian developers automatically have an account on Alioth.
+They can activate it by using the recover password facility.
+External developers can request guest accounts on Alioth.
+
For more information please visit .
+ Goodies for Developers
+
+ LWN Subscriptions
+
+Since October of 2002, HP has sponsored a subscription to LWN for all
+interested Debian developers.
+
+Details on how to get access to this benefit are in
+.
+
+
Managing Packages
@@ -1797,20 +1803,6 @@ 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.
-
-Note: Do not upload to ftp-master cryptographic
-packages which belong to contrib or non-free. Uploads of
-such software should go to non-us (see [). Furthermore packages containing code that is
-patent-restricted by the United States government cannot be uploaded to
-ftp-master; depending on the case they may still be uploaded to
-non-US/non-free (it's in non-free because of distribution issues
-and not because of the license of the software). If you can't upload it to
-ftp-master, then neither can you upload it to backup
-queues that finally also end up on ftp-master. If you are not sure
-whether U.S. patent controls or cryptographic controls apply to your
-package, post a message to &email-debian-devel; and ask.
- ]
You may also find the Debian packages [ or
][ useful
when uploading packages. These handy programs help automate the
@@ -1821,41 +1813,7 @@ and the Debian package ][.
Uploading to non-US
]
-Note: non-us is currently not processed any more.
-
-As discussed above, export controlled software should not be uploaded
-to ftp-master. Instead, upload the package with anonymous FTP
-to non-us.debian.org, placing the files in
-&upload-queue; (again, both [ and ][ can do this for you if invoked properly).
- ]
-Note that U.S. residents or citizens are subject to restrictions on
-export of cryptographic software. As of this writing, U.S. citizens
-are allowed to export some cryptographic software, subject to
-notification rules by the U.S. Department of Commerce. However, this
-restriction has been waived for software which is already available
-outside the U.S. Therefore, any cryptographic software which belongs
-in the main section of the Debian archive and does not depend
-on any package outside of main (e.g., does not depend on
-anything in non-US/main) can be uploaded to ftp-master
-or its queues, described above.
-
-Debian policy does not prevent upload to non-US by U.S. residents or
-citizens, but care should be taken in doing so. It is recommended that
-developers take all necessary steps to ensure that they are not
-breaking current US law by doing an upload to non-US, including
-consulting a lawyer.
-
-For packages in non-US/main, non-US/contrib,
-developers should at least follow the . Maintainers of
-non-US/non-free packages should further consult the of non-free software.
-
-This section is for information only and does not constitute legal
-advice. Again, it is strongly recommended that U.S. citizens and
-residents consult a lawyer before doing uploads to non-US.
+Note: non-us was discontinued with release of sarge.
Delayed uploads
@@ -1888,7 +1846,7 @@ For details, please see section [.
Other upload queues
]
-The scp queues on ftp-master, non-us, and security are mostly unusable
+The scp queues on ftp-master, and security are mostly unusable
due to the login restrictions on those hosts.
The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
@@ -1954,7 +1912,7 @@ or priority for your package be changed from the old section or
priority to the new one. Be sure to explain your reasoning.
For more information about override files, see and
+name="dpkg-scanpackages" section="1"> and
.
Note that the Section field describes both the section as
@@ -2883,7 +2841,56 @@ different sub-flavors of Debian, which may or may not really be of
general interest (for instance, a flavor of Debian built with gcc
bounds checking). It will also enable Debian to recompile entire
distributions quickly.
-
+
+The buildds admins of each arch can be contacted by the mail address
+$arch@buildd.debian.org.
+
+ When your package is not portable
+
+Some packages still have issues with building and/or working on some
+of the architectures supported by Debian, and cannot be ported at all,
+or not with a reasonable amount of time. An example is a package that
+is SVGA-specific (only i386), or uses other hardware-specific features
+not supported on all architectures.
+
+In order to prevent broken packages from being uploaded to the archive, and
+wasting buildd time, you need to do a few things:
+
+
+ -
+
+First, make sure your package does fail to build on
+architectures that it cannot support.
+There are a few ways to achieve this.
+The preferred way is to have a small testsuite during build time
+that will test the functionality, and fail if it doesn't work.
+This is a good idea anyway,
+as this will prevent (some) broken uploads on all architectures,
+and also will allow the package to build
+as soon as the required functionality is available.
+
+Additionally, if you believe the list of supported architectures is
+pretty constant, you should change 'any' to a list of supported
+architectures in debian/control. This way, the build will fail also,
+and indicate this to a human reader without actually trying.
+ -
+
+In order to prevent autobuilders from needlessly trying to build your
+package, it must be included in packages-arch-specific, a
+list used by the wanna-build script.
+The current version is available as
+;
+please see the top of the file for whom to contact for changes.
+
+
+Please note that it is insufficient to only add your package to
+Packages-arch-specific
+without making it fail to build on unsupported architectures:
+A porter or any other person trying to build your package might
+accidently upload it without noticing it doesn't work.
+If in the past some binary packages were uploaded on unsupported architectures,
+request there removal by filing a bug against
+ftp.debian.org
Non-Maintainer Uploads (NMUs)
@@ -4098,7 +4105,7 @@ Most questions should use medium and low priorities.
Most Debian package maintainers are not native English speakers. So,
writing properly phrased templates may not be easy for them.
-Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+Please use (and abuse) &email-debian-l10n-english; mailing
list. Have your templates proofread.
Badly written templates give a poor image of your package, of your
@@ -4112,10 +4119,10 @@ doing so, try to balance between verbosity and simplicity.
Be kind to translators
Debconf templates may be translated. Debconf, along with its sister
-package po-debconf offers a simple framework for getting
+package po-debconf offers a simple framework for getting
templates translated by translation teams or even individuals.
-Please use gettext-based templates. Install po-debconf on your
+Please use gettext-based templates. Install po-debconf on your
development system and read its documentation ("man po-debconf" is a
good start).
@@ -4128,10 +4135,57 @@ additional uploads. If you use gettext-based templates, the
translator's name and e-mail addresses are mentioned in the po files
headers.
+The use of the podebconf-report-po from the
+po-debconf package is highly recommended to warn translators which
+have incomplete translations and request them for updates.
+
If in doubt, you may also contact the translation team for a given
language (debian-l10n-xxxxx@lists.debian.org), or the
-debian-i18n@lists.debian.org mailing list.
+&email-debian-i18n; mailing list.
+
+Calls for translations posted to
+&email-debian-i18n; with the debian/po/templates.pot file
+attached or referenced in a URL are encouraged. Be sure to mentions in
+these calls for new translations which languages you have existing
+translations for, in order to avoid duplicate work.
+ Unfuzzy complete translations when correcting typos and spelling
+
+When the text of a debconf template is corrected and you are
+sure that the change does not affect
+translations, please be kind to translators and unfuzzy their
+translations.
+
+If you don't do so, the whole template will not be translated as long
+as a translator will send you an update.
+
+To unfuzzy translations, you can proceed the following way:
+
+ -
+Put all incomplete PO files out of the way. You can check the
+completeness by using (needs the gettext package installed):
+for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done
+
-
+move all files which report either fuzzy strings to a temporary
+place. Files which report no fuzzy strings (only translated and
+untranslated) will be kept in place.
+
-
+now and now only, modify the template for the typos
+and check again that translation are not impacted (typos, spelling
+errors, sometimes typographical corrections are usually OK)
+
-
+run debconf-updatepo. This will fuzzy all strings
+you modified in translations. You can see this by running the above
+again
+
-
+use the following command:
+for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done
+
-
+move back to debian/po the files which showed fuzzy strings in the first step
+
-
+run debconf-updatepo again
+
Do not make assumptions about interfaces
Templates text should not make reference to widgets belonging to some
@@ -4139,6 +4193,12 @@ debconf interfaces. Sentences like "If you answer Yes..." have no
meaning for users of graphical interfaces which use checkboxes for
boolean questions.
+String templates should also avoid mentioning the default values in
+their description. First, because this is redundant with the values
+seen by the users. Also, because these default values may be different
+from the maintainer choices (for instance, when the debconf database
+was preseeded).
+
More generally speaking, try to avoid referring to user actions.
Just give facts.