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.