From c81927355fe51c8a09827d098d0caad05a052d67 Mon Sep 17 00:00:00 2001 From: debacle Date: Sat, 30 Jun 2007 13:21:18 +0000 Subject: [PATCH] Fixed all examples, fixed many (not all, yet) entities. git-svn-id: svn://anonscm.debian.org/ddp/developers-reference/trunk@4910 313b444b-1b9f-4f58-a734-7bb04f332e8d --- Makefile | 24 ++-- best-pkging-practices.dbk | 114 +++++++---------- beyond-pkging.dbk | 45 ++++--- common.ent | 251 ++++++++++++++++++++++++++++++++++++++ developer-duties.dbk | 28 +++-- index.dbk | 11 +- l10n.dbk | 12 +- new-maintainer.dbk | 48 ++++---- pkgs.dbk | 138 ++++++++++----------- resources.dbk | 215 ++++++++++++-------------------- scope.dbk | 6 +- tools.dbk | 14 ++- 12 files changed, 546 insertions(+), 360 deletions(-) create mode 100644 common.ent diff --git a/Makefile b/Makefile index 8dfc96d..2dfbe39 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Makefile, used for the developers-reference in DocBook XML -SOURCES := $(wildcard *.dbk) +SOURCES := $(wildcard *.dbk *.ent) FORMATS := html txt pdf LANGS := fr ja @@ -12,8 +12,11 @@ TARGETS := $(foreach fmt,$(FORMATS),developers-reference.$(fmt)) \ XP=xsltproc --nonet --novalid --xinclude XL=xmllint --nonet --noout --postvalid --xinclude # fop is currently in contrib, but can go to main, see #366783 -# alternatives: docbook2pdf (seems to die on UTF-8), dblatex (0.2.4 -# just hangs here) and xmllint (not mature enough, waits in NEW) +# Alternatives: +# - dblatex (0.2.6 has a minor problem with programlisting inside of +# footnote, and a major one with lang="ja"); +# - docbook2pdf (seems to die on UTF-8, #431085); and +# - xmllint (not mature enough, waits in NEW, #182445) FOP=fop # The "-k 0" should be removed as soon as the translations are ready TRANSLATE=po4a-translate -f docbook -k 0 @@ -36,9 +39,12 @@ DBK2FO=$$TOP/fop.xsl all: $(TARGETS) .PHONY: validate -validate: +validate: $(SOURCES) $(XL) index.dbk +%/validate: $(addprefix %/,$(SOURCES)) + cd $(@D) && $(XL) index.dbk + .PHONY: developers-reference.html %/developers-reference.html developers-reference.html: $(PWD)/index.html %/developers-reference.html: $(addprefix %/,index.html) @@ -47,18 +53,20 @@ developers-reference.html: $(PWD)/index.html .PRECIOUS: %/index.html index.html: $(PWD)/developers-reference.html %/index.html: $(addprefix %/,$(SOURCES)) - mkdir -p $(@D) || true cd $(@D) && $(XP) $(DBK2HTML) index.dbk # There must be an easier way than recursive make! -.PRECIOUS: %.dbk +.PRECIOUS: %.dbk %.ent ifndef LINGUA -%.dbk: FORCE - [ "$$LINGUA" = . ] || make $@ LINGUA=$(@D) +%.dbk %.ent: FORCE + [ "$$LINGUA" = . ] || $(MAKE) $@ LINGUA=$(@D) FORCE: else $(LINGUA)/%.dbk: %.dbk $(patsubst %.dbk,po4a/$(LINGUA)/%.po,%.dbk) $(TRANSLATE) -m $< -p po4a/$(@:.dbk=.po) -l $@ + +$(LINGUA)/%.ent: %.ent + cd $(@D) && ln -sf ../$(@F) . endif developers-reference.txt: $(PWD)/developers-reference.txt diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index 63b7f87..981c35f 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -1,11 +1,13 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Best Packaging Practices Debian's quality is largely due to the Debian Policy, which +url="&url-debian-policy;">Debian Policy, which defines explicit baseline requirements which all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very @@ -153,7 +155,7 @@ this using an hand-crafted debian/rules file. The following practices are relevant to the debian/control file. They supplement the Policy +url="&url-debian-policy;ch-binary.html#s-descriptions">Policy on package descriptions. @@ -201,7 +203,7 @@ Postscript or postscript. If you are having problems writing your description, you may wish to send it -along to debian-l10n-english@lists.debian.org and request +along to debian-l10n-english@&lists-host; and request feedback. @@ -278,10 +280,10 @@ it. Both ispell and aspell have special modes for checking debian/control files: - -d american -g debian/control +ispell -d american -g debian/control - -d en -D -c debian/control +aspell -d en -D -c debian/control Users usually expect these questions to be answered in the package description: @@ -341,7 +343,7 @@ added at the end of description, using the following format: Note the spaces prepending the line, which serves to break the lines correctly. To see an example of how this displays, see . +url="http://&packages-host;/unstable/web/wml">. If there is no home page for the software, this should naturally be left out. @@ -349,11 +351,11 @@ If there is no home page for the software, this should naturally be left out. Note that we expect this field will eventually be replaced by a proper debian/control field understood by dpkg -and packages.debian.org. If you don't want to bother +and &packages-host;. If you don't want to bother migrating the home page from the description to this field, you should probably wait until that is available. Please make sure that this line matches the regular expression /^ Homepage: [^ ]*$/, as this allows -packages.debian.org to parse it correctly. +&packages-host; to parse it correctly. @@ -427,7 +429,7 @@ the URL is in the svn:// scheme (instead of Best practices for <filename>debian/changelog</filename> The following practices supplement the Policy +url="&url-debian-policy;ch-docs.html#s-changelogs">Policy on changelog files.
@@ -582,7 +584,7 @@ as it will not be automatically checked during build as the changelog is. Here is an example of a real NEWS.Debian file: - (3.0pl1-74) unstable; urgency=low +cron (3.0pl1-74) unstable; urgency=low The checksecurity script is no longer included with the cron package: it now has its own package, checksecurity. If you liked the @@ -613,7 +615,7 @@ NEWS.Debian file in your package. No news is good news! FIXME: presentation of cvs-buildpackage, updating sources via CVS (debian/rules refresh). -"http://www.debian.org/devel/cvs_packages" +"&url-devel-docs;cvs_packages"
--> @@ -626,7 +628,7 @@ Maintainer scripts include the files debian/postinst, debian/postrm. These scripts take care of any package installation or deinstallation setup which isn't handled merely by the creation or removal of files and directories. The following instructions supplement the -Debian Policy. +Debian Policy. Maintainer scripts must be idempotent. That means that you need to make sure @@ -661,27 +663,12 @@ maintainer script. If you need to check for the existence of a command, you should use something like - - [ -x /usr/sbin/install-docs ]; then ... - +if [ -x /usr/sbin/install-docs ]; then ... If you don't wish to hard-code the path of a command in your maintainer script, the following POSIX-compliant shell function may help: - -() { - OLDIFS=$IFS - IFS=: - for p in $PATH; do - if [ -x $p/$* ]; then - IFS=$OLDIFS - return 0 - fi - done - IFS=$OLDIFS - return 1 -} - +&example-pathfind; You can use this function to search $PATH for a command name, passed as an argument. It returns true (zero) if the command was found, @@ -753,7 +740,7 @@ 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 +Please use (and abuse) debian-l10n-english@&lists-host; mailing list. Have your templates proofread. @@ -796,11 +783,11 @@ 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. +(debian-l10n-xxxxx@&lists-host;), or the +debian-i18n@&lists-host; mailing list. -Calls for translations posted to debian-i18n@lists.debian.org +Calls for translations posted to debian-i18n@&lists-host; 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 @@ -831,10 +818,8 @@ Put all incomplete PO files out of the way. You can check the completeness by using (needs the gettext package installed): - - i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null ---statistics $i; done - +for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null +--statistics $i; done @@ -860,9 +845,7 @@ modified in translations. You can see this by running the above again use the following command: - - i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done - +for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done @@ -1206,7 +1189,7 @@ using English. Example, taken from the geneweb package templates: -: geneweb/lang +Template: geneweb/lang Type: select __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) # This is the default choice. Translators may put their own language here @@ -1300,7 +1283,7 @@ differences between two versions of the documentation, so, for instance, they can see what needs to be retranslated. It is recommended that the translated documentation maintain a note about what source control revision the translation is based on. An interesting system is provided by doc-check in the boot-floppies package, which shows an overview of the translation status for any given language, using structured comments for @@ -1337,7 +1320,7 @@ Keeping autoconf's config.sub and especially on more volatile architectures. Some very good packaging practices for any package using autoconf and/or automake have been synthesized in -/usr/share/doc/autotools-dev/README.Debian.gz from the +&file-bpp-autotools; from the autotools-dev package. You're strongly encouraged to read this file and to follow the given recommendations. @@ -1353,7 +1336,7 @@ library can result in dozens of dependent packages breaking. Good practices for library packaging have been grouped in the library +url="&url-libpkg-guide;">the library packaging guide. @@ -1362,7 +1345,7 @@ packaging guide. Documentation Be sure to follow the Policy on +url="&url-debian-policy;ch-docs.html">Policy on documentation. @@ -1395,7 +1378,7 @@ packaging rules and practices: Perl related packages have a Perl +url="&url-perl-policy;">Perl policy, some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module). @@ -1411,14 +1394,14 @@ Python related packages have their python policy; see Emacs related packages have the emacs +url="&url-emacs-policy;">emacs policy. Java related packages have their java +url="&url-java-policy;">java policy. @@ -1440,7 +1423,7 @@ in the sgml-base-doc package. Lisp packages should register themselves with common-lisp-controller, about which see -/usr/share/doc/common-lisp-controller/README.packaging. +&file-lisp-controller;. @@ -1495,12 +1478,12 @@ If you need a certain locale during build, you can create a temporary file via this trick: -If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name +If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name of the locale you generate, you should get what you want without being root. Something like this: -=debian/tmpdir/usr/lib/locale +LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 @@ -1530,18 +1513,8 @@ description. So, when you are creating such a package, please make sure to add this text to your short description. If you are looking for examples, just run: - - --cache search .|grep dummy - - -or - - --cache search .|grep transitional - - -. +apt-cache search .|grep dummy or +apt-cache search .|grep transitional. @@ -1585,7 +1558,7 @@ tarballs as pristine source. Its strategy is equivalent to the following: It unpacks the tarball in an empty temporary directory by doing - path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - +zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - @@ -1648,7 +1621,7 @@ repackaged source was obtained, and how this can be reproduced in the get-orig-source target in your debian/rules file that repeats the process, as described in the Policy Manual, Main +url="&url-debian-policy;ch-source.html#s-debianrules">Main building script: debian/rules. @@ -1718,9 +1691,10 @@ postfix indicating the encoding should be appended to the original filename. Note that you don't need to depend on sharutils to get the uudecode program if you use perl's pack function. -The code could look like -file: perl -ne 'print(pack u, $$_);' -$(file) > $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);' -$(file).uuencoded > $(file) . The file would then be +The code could look like + +&example-uu; +. The file would then be decoded and copied to its place during the build process. Thus the change will be visible quite easy. @@ -1788,7 +1762,7 @@ Note that the Debian package should depend on the package that it provides debugging symbols for, and this dependency should be versioned. For example: -: libfoo-dbg (= ${binary:Version}) +Depends: libfoo-dbg (= ${binary:Version}) diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk index f5c7be8..9b8de92 100644 --- a/beyond-pkging.dbk +++ b/beyond-pkging.dbk @@ -1,6 +1,8 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Beyond Packaging @@ -21,9 +23,9 @@ Debian developers are often the first line testers. Finding and reporting bugs in other developers' packages improves the quality of Debian. -Read the instructions for +Read the instructions for reporting bugs in the Debian bug tracking system. +url="&url-bts;">bug tracking system. Try to submit the bug from a normal user account at which you are likely to @@ -38,7 +40,7 @@ generally ease the process. Make sure the bug is not already filed against a package. Each package has a bug list easily reachable at -http://bugs.debian.org/packagename +http://&bugs-host;/packagename Utilities like querybts 1 can also provide you with this information (and reportbug will usually invoke @@ -62,7 +64,7 @@ From time to time you may want to check what has been going on with the bug reports that you submitted. Take this opportunity to close those that you can't reproduce anymore. To find out all the bugs you submitted, you just have to visit -http://bugs.debian.org/from:<your-email-addr>. +http://&bugs-host;/from:<your-email-addr>.
Reporting lots of bugs at once (mass bug filing) @@ -75,7 +77,7 @@ role="package">lintian so that an error or warning is emitted. If you report more than 10 bugs on the same topic at once, it is recommended -that you send a message to debian-devel@lists.debian.org +that you send a message to debian-devel@&lists-host; describing your intention before submitting the report, and mentioning the fact in the subject of your mail. This will allow other developers to verify that the bug is a real problem. In addition, it will help prevent a situation in @@ -85,11 +87,11 @@ which several maintainers start filing the same bug report simultaneously. Please use the programms dd-list and if appropriate whodepends (from the package devscripts) to generate a list of all affected packages, and include the output in your mail to -debian-devel@lists.debian.org. +debian-devel@&lists-host;. Note that when sending lots of bugs on the same subject, you should send the -bug report to maintonly@bugs.debian.org so that the bug report +bug report to maintonly@&bugs-host; so that the bug report is not forwarded to the bug distribution mailing list.
@@ -108,8 +110,8 @@ linkend="lintian"/> ) as possible. If you do not find that possible, then you should consider orphaning some of your packages (see ). Alternatively, you may ask the help of other people in order to catch up with the backlog of bugs that you have (you can ask for -help on debian-qa@lists.debian.org or -debian-devel@lists.debian.org). At the same time, you can look +help on debian-qa@&lists-host; or +debian-devel@&lists-host;). At the same time, you can look for co-maintainers (see ). @@ -119,7 +121,7 @@ for co-maintainers (see ). From time to time the QA group organizes bug squashing parties to get rid of as many problems as possible. They are announced on -debian-devel-announce@lists.debian.org and the announcement +debian-devel-announce@&lists-host; and the announcement explains which area will be the focus of the party: usually they focus on release critical bugs but it may happen that they decide to help finish a major upgrade (like a new perl version which requires recompilation of all the binary @@ -160,7 +162,7 @@ version is available and that you need it. Looking up the email address of the maintainer for the package can be distracting. Fortunately, there is a simple email alias, -<package>@packages.debian.org, which provides a way to +<package>@&packages-host;, which provides a way to email the maintainer, whatever their individual email address (or addresses) may be. Replace <package> with the name of a source or a binary package. @@ -168,7 +170,7 @@ or a binary package. You may also be interested in contacting the persons who are subscribed to a given source package via . You can do so -by using the <package>@packages.qa.debian.org email +by using the <package>@&pts-host; email address. @@ -189,12 +191,7 @@ maintainers who are deemed Missing In Action is recorded. When a member of the QA group contacts an inactive maintainer or finds more information about one, this is recorded in the MIA database. This system is available in /org/qa.debian.org/mia on the host qa.debian.org, and can be queried with a -tool known as mia-query. Use - - --query --help - - +tool known as mia-query. Use mia-query --help to see how to query the database. If you find that no information has been recorded about an inactive maintainer yet, or that you can add more information, you should generally proceed as follows. @@ -215,7 +212,7 @@ maintainer in question as possible. This includes: The echelon information available through the developers' LDAP database, which indicates +url="&url-debian-db;">developers' LDAP database, which indicates when the developer last posted to a Debian mailing list. (This includes uploads via debian-*-changes lists.) Also, remember to check whether the maintainer is marked as on vacation in the database. @@ -248,7 +245,7 @@ happened to the person they sponsored. It is also allowed to post a query to -debian-devel@lists.debian.org, asking if anyone is aware of the +debian-devel@&lists-host;, asking if anyone is aware of the whereabouts of the missing maintainer. Please Cc: the person in question. @@ -348,7 +345,7 @@ package is in acceptable shape. Being a sponsor means being a mentor. Once the package meets Debian standards, build and sign it with --buildpackage -kKEY-ID +dpkg-buildpackage -kKEY-ID before uploading it to the incoming directory. Of course, you can also use any @@ -375,7 +372,7 @@ linkend="pkg-tracking-system"/> . Advocating new developers See the page about advocating a prospective +url="&url-devel-docs;join/nm-advocate">advocating a prospective developer at the Debian web site. @@ -384,7 +381,7 @@ developer at the Debian web site. Handling new maintainer applications Please see Checklist for Application +url="&url-devel-docs;join/nm-amchecklist">Checklist for Application Managers at the Debian web site. diff --git a/common.ent b/common.ent new file mode 100644 index 0000000..5a09ece --- /dev/null +++ b/common.ent @@ -0,0 +1,251 @@ + + + + + + + + + + + + +/usr/share/common-licenses/GPL"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +/org/ftp.debian.org/incoming/"> +/org/non-us.debian.org/incoming/"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +listmaster@&lists-host;"> +debian-announce@&lists-host;"> +developers-reference@&packages-host;"> +debian-changes@lists.debian.org"> +debian-devel@&lists-host;"> +debian-devel-announce@&lists-host;"> +debian-devel-changes@lists.debian.org"> +debian-devel-REQUEST@&lists-host;"> +debian-i18n@&lists-host;"> +debian-mentors@&lists-host;"> +debian-private@&lists-host;"> +debian-project@&lists-host;"> +debian-policy@&lists-host;"> +debian-user@&lists-host;"> + +debian-qa@&lists-host;"> +debian-release@&lists-host;"> +debian-email@&lists-host;"> +debian-vote@&lists-host;"> +debian-security-announce@&lists-host;"> +debian-l10n-english@&lists-host;"> +mia@qa.debian.org"> + +new-maintainer@debian.org"> +keyring-maint@debian.org"> +debian-admin@debian.org"> +ftpmaster@debian.org"> +override-change@debian.org"> +wnpp@debian.org"> +control@&bugs-host;"> +team@security.debian.org"> + + +/usr/share/doc/debian/mailing-lists.txt"> +/usr/share/doc/debian/bug-*"> +/usr/share/doc/python/python-policy.txt.gz"> +/usr/share/doc/ocaml/ocaml_packaging_policy.gz"> +/usr/share/doc/common-lisp-controller/README.packaging"> + +/usr/share/doc/autotools-dev/README.Debian.gz"> + +address" | mail request@&bugs-host;'> + + +subkeys.pgp.net"> + +dists/stable/main/ +dists/stable/main/binary-i386/ +dists/stable/main/binary-m68k/ +dists/stable/main/binary-alpha/ + ... +dists/stable/main/source/ + ... +dists/stable/main/disks-i386/ +dists/stable/main/disks-m68k/ +dists/stable/main/disks-alpha/ + ... + +dists/stable/contrib/ +dists/stable/contrib/binary-i386/ +dists/stable/contrib/binary-m68k/ +dists/stable/contrib/binary-alpha/ + ... +dists/stable/contrib/source/ + +dists/stable/non-free/ +dists/stable/non-free/binary-i386/ +dists/stable/non-free/binary-m68k/ +dists/stable/non-free/binary-alpha/ + ... +dists/stable/non-free/source/ + +dists/testing/ +dists/testing/main/ + ... +dists/testing/contrib/ + ... +dists/testing/non-free/ + ... + +dists/unstable +dists/unstable/main/ + ... +dists/unstable/contrib/ + ... +dists/unstable/non-free/ + ... + +pool/ +pool/main/a/ +pool/main/a/apt/ + ... +pool/main/b/ +pool/main/b/bash/ + ... +pool/main/liba/ +pool/main/liba/libalias-perl/ + ... +pool/main/m/ +pool/main/m/mailx/ + ... +pool/non-free/n/ +pool/non-free/n/netscape/ + ..."> + +uuencode-file: + perl -ne 'print(pack "u", $$_);' $(file) > $(file).uuencoded + +uudecode-file: + perl -ne 'print(unpack "u", $$_);' $(file).uuencoded > $(file)"> + +pathfind() { + OLDIFS="$IFS" + IFS=: + for p in $PATH; do + if [ -x "$p/$*" ]; then + IFS="$OLDIFS" + return 0 + fi + done + IFS="$OLDIFS" + return 1 +}'> diff --git a/developer-duties.dbk b/developer-duties.dbk index 899b567..5a444e7 100644 --- a/developer-duties.dbk +++ b/developer-duties.dbk @@ -1,13 +1,15 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Debian Developer's Duties
Maintaining your Debian information There's a LDAP database containing information about Debian developers at -. You should enter your +. You should enter your information there and update it as it changes. Most notably, make sure that the address where your debian.org email gets forwarded to is always up to date, as well as the address where you get your debian-private subscription if you @@ -37,7 +39,7 @@ lost. If you add signatures to your public key, or add user identities, you can update the Debian key ring by sending your key to the key server at -keyring.debian.org. +&keyserver-host;. If you need to add a completely new key or remove an old key, you need to get @@ -45,7 +47,7 @@ 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 might reject the new key. Details can be found at . +url="http://&keyserver-host;/replacing_keys.html">. The same key extraction routines discussed in @@ -63,26 +65,26 @@ package. Even though Debian isn't really a democracy, we use a democratic process to elect our leaders and to approve general resolutions. These procedures are -defined by the Debian +defined by the Debian Constitution. Other than the yearly leader election, votes are not routinely held, and they are not undertaken lightly. Each proposal is first discussed on the -debian-vote@lists.debian.org mailing list and it requires +debian-vote@&lists-host; mailing list and it requires several endorsements before the project secretary starts the voting procedure. You don't have to track the pre-vote discussions, as the secretary will issue several calls for votes on -debian-devel-announce@lists.debian.org (and all developers are +debian-devel-announce@&lists-host; (and all developers are expected to be subscribed to that list). Democracy doesn't work well if people don't take part in the vote, which is why we encourage all developers to vote. Voting is conducted via GPG-signed/encrypted email messages. The list of all proposals (past and current) is available on the Debian Voting Information page, along +url="&url-vote;">Debian Voting Information page, along with information on how to make, second and vote on proposals.
@@ -105,7 +107,7 @@ unavailable. In order to inform the other developers, there are two things that you should -do. First send a mail to debian-private@lists.debian.org with +do. First send a mail to debian-private@&lists-host; with [VAC] prepended to the subject of your message This is so that the message can be easily filtered by people who don't want to read vacation notices. and state the period of time when you will be on @@ -120,7 +122,7 @@ the on vacation flag when you come back! Ideally, you should sign up at the GPG coordination site when booking a +url="&url-newmaint-db;gpg.php">GPG coordination site when booking a holiday and check if anyone there is looking for signing. This is especially important when people go to exotic places where we don't have any developers yet but where there are people who are interested in applying. @@ -166,12 +168,12 @@ the removal of a package at freeze time. That's why these bugs need to be corrected as quickly as possible. -Developers who are part of the Quality +Developers who are part of the Quality Assurance group are following all such bugs, and trying to help whenever possible. If, for any reason, you aren't able fix an RC bug in a package of yours within 2 weeks, you should either ask for help by sending a mail to the Quality Assurance (QA) group -debian-qa@lists.debian.org, or explain your difficulties and +debian-qa@&lists-host;, or explain your difficulties and present a plan to fix them by sending a mail to the bug report. Otherwise, people from the QA group may want to do a Non-Maintainer Upload (see ) after trying to contact you (they might not wait as long as @@ -195,7 +197,7 @@ Orphan all your packages, as described in . Send an gpg-signed email about why you are leaving the project to -debian-private@lists.debian.org. +debian-private@&lists-host;. diff --git a/index.dbk b/index.dbk index bba1fa9..5312fde 100644 --- a/index.dbk +++ b/index.dbk @@ -1,13 +1,15 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Debian Developer's Reference Developer's Reference Team -developers-reference@packages.debian.org +developers-reference@&packages-host; Andreas Barth @@ -66,11 +68,10 @@ more details. A copy of the GNU General Public License is available as -/usr/share/common-licenses/GPL in the Debian GNU/Linux +&file-GPL; in the &debian-formal; distribution or on the World Wide Web at the GNU web site. You can -also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin -Street, Fifth Floor, Boston, MA 02110-1301, USA. +also obtain it by writing to the &fsf-addr;. If you want to print this reference, you should use the + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Internationalizing, translating, being internationalized and being translated @@ -13,7 +15,7 @@ programs, you should read most of this chapter. According to Introduction to +url="http://&www-debian-org;/doc/manuals/intro-i18n/">Introduction to i18n from Tomohiro KUBOTA, I18N (internationalization) means modification of a software or related technologies so that a software can potentially handle multiple languages, customs, and so on in the world. while @@ -48,7 +50,7 @@ Project, the Gnome translation Project or the KDE one. The only centralized resource within Debian is the Central Debian translation +url="http://&www-debian-org;/intl/l10n/">Central Debian translation statistics, where you can find some statistics about the translation files found in the actual packages, but no real infrastructure to ease the translation process. @@ -65,7 +67,7 @@ For debconf templates, maintainers should use the po-debconf package to ease the work of translators, who could use the DDTP to do their work (but the French and Brazilian teams don't). Some statistics can be found both on the DDTP site (about what is actually translated), and on the Central Debian translation +url="http://&www-debian-org;/intl/l10n/">Central Debian translation statistics site (about what is integrated in the packages). @@ -87,7 +89,7 @@ same way as its program messages. There is an effort to handle Debian-specific man pages within a specific CVS +url="&url-cvsweb;manpages/?cvsroot=debian-doc">specific CVS repository. diff --git a/new-maintainer.dbk b/new-maintainer.dbk index c52583a..615d85e 100644 --- a/new-maintainer.dbk +++ b/new-maintainer.dbk @@ -1,27 +1,29 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Applying to Become a Maintainer
Getting started So, you've read all the documentation, you've gone through the Debian New Maintainers' +url="http://&www-debian-org;/doc/maint-guide/">Debian New Maintainers' Guide, understand what everything in the hello example package is for, and you're about to Debianize your favorite piece of software. How do you actually become a Debian developer so that your work can be incorporated into the Project? -Firstly, subscribe to debian-devel@lists.debian.org if you +Firstly, subscribe to debian-devel@&lists-host; if you haven't already. Send the word subscribe in the Subject of an email to -debian-devel-REQUEST@lists.debian.org. In case of problems, -contact the list administrator at listmaster@lists.debian.org. +debian-devel-REQUEST@&lists-host;. In case of problems, +contact the list administrator at listmaster@&lists-host;. More information on available mailing lists can be found in . -debian-devel-announce@lists.debian.org is another list which is +debian-devel-announce@&lists-host; is another list which is mandatory for anyone who wishes to follow Debian's development. @@ -31,19 +33,19 @@ something to avoid duplicated effort. Another good list to subscribe to is -debian-mentors@lists.debian.org. See +debian-mentors@&lists-host;. See for details. The IRC channel #debian can also be helpful; see . -When you know how you want to contribute to Debian GNU/Linux, you should get in +When you know how you want to contribute to &debian-formal;, you should get in contact with existing Debian maintainers who are working on similar tasks. That way, you can learn from experienced developers. For example, if you are interested in packaging existing software for Debian, you should try to get a sponsor. A sponsor will work together with you on your package and upload it to the Debian archive once they are happy with the packaging work you have done. You can find a sponsor by mailing the -debian-mentors@lists.debian.org mailing list, describing your +debian-mentors@&lists-host; mailing list, describing your package and yourself and asking for a sponsor (see and for @@ -56,14 +58,14 @@ maintainers already working on these tasks and submit patches and improvements. One pitfall could be a too-generic local part in your mailadress: Terms like mail, admin, root, master should be avoided, please see for details. +url="&url-debian-lists;"> for details.
Debian mentors and sponsors -The mailing list debian-mentors@lists.debian.org has been set up +The mailing list debian-mentors@&lists-host; has been set up for novice maintainers who seek help with initial packaging and other developer-related issues. Every new developer is invited to subscribe to that list (see for details). @@ -94,22 +96,22 @@ If you wish to be a mentor and/or sponsor, more information is available in
Registering as a Debian developer -Before you decide to register with Debian GNU/Linux, you will need to read all +Before you decide to register with &debian-formal;, you will need to read all the information available at the New Maintainer's +url="&url-newmaint;">New Maintainer's Corner. It describes in detail the preparations you have to do before you can register to become a Debian developer. For example, before you apply, -you have to read the Debian +you have to read the Debian Social Contract. Registering as a developer means that you agree with and pledge to uphold the Debian Social Contract; it is very important that -maintainers are in accord with the essential ideas behind Debian GNU/Linux. +maintainers are in accord with the essential ideas behind &debian-formal;. Reading the GNU Manifesto would also be a good idea. The process of registering as a developer is a process of verifying your identity and intentions, and checking your technical skills. As the number of -people working on Debian GNU/Linux has grown to over 900 and our systems are +people working on &debian-formal; has grown to over &number-of-maintainers; and our systems are used in several very important places, we have to be careful about being compromised. Therefore, we need to verify new maintainers before we can give them accounts on our servers and let them upload packages. @@ -128,12 +130,12 @@ Registration requires that you are familiar with Debian's philosophy and technical documentation. Furthermore, you need a GnuPG key which has been signed by an existing Debian maintainer. If your GnuPG key is not signed yet, you should try to meet a Debian Developer in person to get your key signed. -There's a GnuPG Key Signing +There's a GnuPG Key Signing Coordination page which should help you find a Debian Developer close to you. (If there is no Debian Developer close to you, alternative ways to pass the ID check may be permitted as an absolute exception on a case-by-case-basis. See the identification page for +url="&url-devel-docs;join/nm-step2">identification page for more information.) @@ -178,8 +180,8 @@ have to manually add those signatures. If your public key isn't on a public key server such as -subkeys.pgp.net, please read the documentation available at -NM Step 2: +&pgp-keyserv;, please read the documentation available at +NM Step 2: Identification. That document contains instructions on how to put your key on the public key servers. The New Maintainer Group will put your public key on the servers if it isn't already there. @@ -202,16 +204,16 @@ has to express their belief that you can contribute to Debian successfully. When you have found an advocate, have your GnuPG key signed and have already contributed to Debian for a while, you're ready to apply. You can simply -register on our application +register on our application page. After you have signed up, your advocate has to confirm your application. When your advocate has completed this step you will be assigned an Application Manager who will go with you through the necessary steps of the New Maintainer process. You can always check your status on the applications status board. +url="&url-newmaint-db;">applications status board. For more details, please consult New Maintainer's Corner +url="&url-newmaint;">New Maintainer's Corner at the Debian web site. Make sure that you are familiar with the necessary steps of the New Maintainer process before actually applying. If you are well prepared, you can save a lot of time later on. diff --git a/pkgs.dbk b/pkgs.dbk index 5004933..fdf7a0f 100644 --- a/pkgs.dbk +++ b/pkgs.dbk @@ -1,6 +1,8 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Managing Packages @@ -11,10 +13,10 @@ and porting packages. New packages If you want to create a new package for the Debian distribution, you should -first check the Work-Needing and +first check the Work-Needing and Prospective Packages (WNPP) list. Checking the WNPP list ensures that no one is already working on packaging that software, and that effort is not -duplicated. Read the WNPP web +duplicated. Read the WNPP web pages for more information. @@ -30,7 +32,7 @@ You should set the subject of the bug to ``ITP: foo -- short description'', substituting the name of the new package for foo. The severity of the bug report must be set to wishlist. If you feel it's necessary, send -a copy to debian-devel@lists.debian.org by putting the address +a copy to debian-devel@&lists-host; by putting the address in the X-Debbugs-CC: header of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number). @@ -87,7 +89,7 @@ of what is going on, and what is new, in the project. -Please see +Please see for common rejection reasons for a new package.
@@ -336,7 +338,7 @@ packages uninstallable, is strongly discouraged. The Release Team (which can be reached at -debian-release@lists.debian.org) will regularly evaluate the +debian-release@&lists-host;) will regularly evaluate the uploads To stable-proposed-updates and decide if your package can be included in stable. Please be clear (and verbose, if necessary) in your changelog entries for uploads to @@ -367,9 +369,9 @@ section for details. Uploading to <literal>ftp-master</literal> To upload a package, you should upload the files (including the signed changes -and dsc-file) with anonymous ftp to ftp-master.debian.org in +and dsc-file) with anonymous ftp to &ftp-master-host; in the directory /pub/UploadQueue/. +url="ftp://&ftp-master-host;&upload-queue;">&upload-queue;. To get the files processed there, they need to be signed with a key in the debian keyring. @@ -511,7 +513,7 @@ file. To alter the actual section that a package is put in, you need to first make sure that the debian/control file in your package is accurate. Next, send an email override-change@debian.org or -submit a bug against ftp.debian.org +submit a bug against &ftp-debian-org; 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. @@ -519,14 +521,14 @@ old section or priority to the new one. Be sure to explain your reasoning. For more information about override files, see dpkg-scanpackages 1 and . +url="&url-bts-devel;#maintincorrect">. Note that the Section field describes both the section as well as the subsection, which are described in . If the section is main, it should be omitted. The list of allowable subsections can be found in . +url="&url-debian-policy;ch-archive.html#s-subsections">.
@@ -534,13 +536,13 @@ url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections">Handling bugs Every developer has to be able to work with the Debian bug tracking system. This includes +url="&url-bts;">bug tracking system. This includes knowing how to file bug reports properly (see ), how to update them and reorder them, and how to process and close them. The bug tracking system's features are described in the BTS documentation for +url="&url-bts-devel;">BTS documentation for developers. This includes closing bugs, sending followup messages, assigning severities and tags, marking bugs as forwarded, and other issues. @@ -549,22 +551,22 @@ Operations such as reassigning bugs to other packages, merging separate bug reports about the same issue, or reopening bugs when they are prematurely closed, are handled using the so-called control mail server. All of the commands available on this server are described in the BTS control server +url="&url-bts-control;">BTS control server documentation.
Monitoring bugs If you want to be a good maintainer, you should periodically check the Debian bug tracking system (BTS) for +url="&url-bts;">Debian bug tracking system (BTS) for your packages. The BTS contains all the open bugs against your packages. You can check them by browsing this page: -http://bugs.debian.org/yourlogin@debian.org. +http://&bugs-host;/yourlogin@debian.org. Maintainers interact with the BTS via email addresses at -bugs.debian.org. Documentation on available commands can be -found at , or, if you have +&bugs-host;. Documentation on available commands can be +found at , or, if you have installed the doc-debian package, you can look at the local files /usr/share/doc/debian/bug-*. @@ -575,7 +577,7 @@ open bugs against your packages: # ask for weekly reports of bugs in my packages -0 17 * * fri echo index maint address | mail request@bugs.debian.org +&cron-bug-report; Replace address with your official Debian maintainer @@ -588,11 +590,11 @@ address. When responding to bugs, make sure that any discussion you have about bugs is sent both to the original submitter of the bug, and to the bug itself (e.g., -123@bugs.debian.org). If you're writing a new mail and you +123@&bugs-host;). If you're writing a new mail and you don't remember the submitter email address, you can use the -123-submitter@bugs.debian.org email to contact the submitter +123-submitter@&bugs-host; email to contact the submitter and to record your mail within the bug log (that means you -don't need to send a copy of the mail to 123@bugs.debian.org). +don't need to send a copy of the mail to 123@&bugs-host;). If you get a bug which mentions FTBFS, this means Fails to build from source. @@ -601,14 +603,14 @@ Porters frequently use this acronym. Once you've dealt with a bug report (e.g. fixed it), mark it as done (close it) by sending an explanation message to -123-done@bugs.debian.org. If you're fixing a bug by changing +123-done@&bugs-host;. If you're fixing a bug by changing and uploading the package, you can automate bug closing as described in . You should never close bugs via the bug server close command sent to -control@bugs.debian.org. If you do so, the original submitter +control@&bugs-host;. If you do so, the original submitter will not receive any information about why the bug was closed.
@@ -619,10 +621,10 @@ will not receive any information about why the bug was closed. As a package maintainer, you will often find bugs in other packages or have bugs reported against your packages which are actually bugs in other packages. The bug tracking system's features are described in the BTS documentation for Debian +url="&url-bts-devel;">BTS documentation for Debian developers. Operations such as reassigning, merging, and tagging bug reports are described in the BTS control server +url="&url-bts-control;">BTS control server documentation. This section contains some guidelines for managing your own bugs, based on the collective Debian developer experience. @@ -655,7 +657,7 @@ unacceptable, you (or the submitter) may want to require a decision of the technical committee by reassigning the bug to tech-ctte (you may use the clone command of the BTS if you wish to keep it reported against your package). Before doing so, please -read the recommended +read the recommended procedure. @@ -664,7 +666,7 @@ procedure. If the bug is real but it's caused by another package, just reassign the bug to the right package. If you don't know which package it should be reassigned to, you should ask for help on IRC or -on debian-devel@lists.debian.org. Please make sure that the +on debian-devel@&lists-host;. Please make sure that the maintainer(s) of the package the bug is reassigned to know why you reassigned it. @@ -701,8 +703,8 @@ someone, the bug may be closed. If the bug is related to the packaging, you just fix it. If you are not able to fix it yourself, then tag the bug as help. You can also -ask for help on debian-devel@lists.debian.org or -debian-qa@lists.debian.org. If it's an upstream problem, you +ask for help on debian-devel@&lists-host; or +debian-qa@&lists-host;. If it's an upstream problem, you have to forward it to the upstream author. Forwarding a bug is not enough, you have to check at each release if the bug has been fixed or not. If it has, you just close it, otherwise you have to remind the author about it. If you have @@ -748,7 +750,7 @@ file, following a certain syntax, and the archive maintenance software will close the bugs for you. For example: --cannon (3.1415) unstable; urgency=low +acme-cannon (3.1415) unstable; urgency=low * Frobbed with options (closes: Bug#98339) * Added safety to prevent operator dismemberment, closes: bug#98765, @@ -782,9 +784,9 @@ If you happen to mistype a bug number or forget a bug in the changelog entries, don't hesitate to undo any damage the error caused. To reopen wrongly closed bugs, send a reopen XXX command to the bug tracking system's control address, -control@bugs.debian.org. To close any remaining bugs that were +control@&bugs-host;. To close any remaining bugs that were fixed by your upload, email the .changes file to -XXX-done@bugs.debian.org, where XXX +XXX-done@&bugs-host;, where XXX is the bug number, and put Version: YYY and an empty line as the first two lines of the body of the email, where YYY is the first version where the bug has been fixed. @@ -793,7 +795,7 @@ first version where the bug has been fixed. Bear in mind that it is not obligatory to close bugs using the changelog as described above. If you simply want to close bugs that don't have anything to do with an upload you made, do it by emailing an explanation to -XXX-done@bugs.debian.org. Do XXX-done@&bugs-host;. Do not close bugs in the changelog entry of a version if the changes in that version of the package don't have any bearing on the bug. @@ -931,8 +933,8 @@ has become public. Security advisories are only issued for the current, released stable distribution, and not for testing or unstable. When released, advisories are sent to the -debian-security-announce@lists.debian.org mailing list and -posted on the security web +debian-security-announce@&lists-host; mailing list and +posted on the security web page. Security advisories are written and posted by the security team. However they certainly do not mind if a maintainer can supply some of the information for them, or write part of the text. Information that should be in @@ -1191,14 +1193,14 @@ chapter gives guidelines on what to do in these cases. Sometimes a package will change its section. For instance, a package from the `non-free' section might be GPL'd in a later version, in which case the package should be moved to `main' or `contrib'. See the Debian Policy Manual for +url="&url-debian-policy;">Debian Policy Manual for guidelines on what section a package belongs in. If you need to change the section for one of your packages, change the package control information to place the package in the desired section, and re-upload the package (see the Debian Policy Manual for +url="&url-debian-policy;">Debian Policy Manual for details). You must ensure that you include the .orig.tar.gz in your upload (even if you are not uploading a new upstream version), or it will not appear in the new section together with @@ -1220,7 +1222,7 @@ described in . If for some reason you want to completely remove a package (say, if it is an old compatibility library which is no longer required), you need to file a bug -against ftp.debian.org asking that the package be removed; +against &ftp-debian-org; asking that the package be removed; as all bugs, this bug should normally have normal severity. Make sure you indicate which distribution the package should be removed from. Normally, you can only have packages removed from unstable and @@ -1253,18 +1255,18 @@ maintainer. Further information relating to these and other package removal related topics may be found at -and . +and . If in doubt concerning whether a package is disposable, email -debian-devel@lists.debian.org asking for opinions. Also of +debian-devel@&lists-host; asking for opinions. Also of interest is the apt-cache program from the apt package. When invoked as apt-cache showpkg package, the program will show details for package, including reverse depends. Other useful programs include apt-cache rdepends, apt-rdepends and grep-dctrl. Removal of -orphaned packages is discussed on debian-qa@lists.debian.org. +orphaned packages is discussed on debian-qa@&lists-host;. Once the package has been removed, the package's bugs should be handled. They @@ -1296,9 +1298,9 @@ occur too often anyway. When you make a mistake naming your package, you should follow a two-step process to rename it. First, set your debian/control file to replace and conflict with the obsolete name of the package (see the Debian Policy Manual for +url="&url-debian-policy;">Debian Policy Manual for details). Once you've uploaded the package and the package has moved into the -archive, file a bug against ftp.debian.org asking to remove +archive, file a bug against &ftp-debian-org; asking to remove the package with the obsolete name. Do not forget to properly reassign the package's bugs at the same time. @@ -1321,7 +1323,7 @@ mirror network. If you can no longer maintain a package, you need to inform others, and see that the package is marked as orphaned. You should set the package maintainer -to Debian QA Group <packages@qa.debian.org> and submit +to Debian QA Group <&pts-host;> and submit a bug report against the pseudo package wnpp. The bug report should be titled O: package -- short @@ -1329,7 +1331,7 @@ description indicating that the package is now orphaned. The severity of the bug should be set to normal; if the package has a priority of standard or higher, it should be set to important. If you feel it's necessary, send a copy -to debian-devel@lists.debian.org by putting the address in the +to debian-devel@&lists-host; by putting the address in the X-Debbugs-CC: header of the message (no, don't use CC:, because that way the message's subject won't indicate the bug number). @@ -1342,7 +1344,7 @@ description. RFA stands for Request For Adoption. -More information is on the WNPP +More information is on the WNPP web pages. @@ -1351,7 +1353,7 @@ web pages. Adopting a package A list of packages in need of a new maintainer is available in the Work-Needing and Prospective Packages +url="&url-wnpp;">Work-Needing and Prospective Packages list (WNPP). If you wish to take over maintenance of any of the packages listed in the WNPP, please take a look at the aforementioned page for information and procedures. @@ -1369,7 +1371,7 @@ package. Complaints about maintainers should be brought up on the developers' mailing list. If the discussion doesn't end with a positive conclusion, and the issue is of a technical nature, consider bringing it to the attention of the technical committee (see the technical committee web +url="&url-devel-docs;tech-ctte">technical committee web page for more information). @@ -1400,7 +1402,7 @@ different from the original architecture of the package maintainer's binary package. It is a unique and essential activity. In fact, porters do most of the actual compiling of Debian packages. For instance, for a single i386 binary package, there must be a recompile for each -architecture, which amounts to 12 more builds. +architecture, which amounts to &number-of-arches; more builds.
Being kind to porters @@ -1445,7 +1447,7 @@ If you can't set up a proper chroot, dpkg-depcheck may be of assistance (see ). -See the Debian Policy +See the Debian Policy Manual for instructions on setting build dependencies. @@ -1453,7 +1455,7 @@ Manual for instructions on setting build dependencies. Don't set architecture to a value other than ``all'' or ``any'' unless you really mean it. In too many cases, maintainers don't follow the instructions -in the Debian Policy +in the Debian Policy Manual. Setting your architecture to ``i386'' is usually incorrect. @@ -1646,11 +1648,11 @@ tools; see the package documentation or references for full information. Mailing lists and web pages Web pages containing the status of each port can be found at . +url="&url-debian-ports;">. Each port of Debian has a mailing list. The list of porting mailing lists can -be found at . These +be found at . These lists are used to coordinate porters, and to connect the users of a given port with the porters. @@ -1688,7 +1690,7 @@ such as andrea and wanna-build. Some of the data produced by buildd which is generally useful to porters is available on the web at . This data includes nightly updated +url="&url-buildd;">. This data includes nightly updated information from andrea (source dependencies) and quinn-diff (packages needing recompilation). @@ -1744,7 +1746,7 @@ 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 ; +url="&url-cvsweb;srcdep/Packages-arch-specific?cvsroot=dak">; please see the top of the file for whom to contact for changes. @@ -1756,7 +1758,7 @@ 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 their removal by filing a bug against ftp.debian.org +role="package">&ftp-debian-org;
@@ -2029,9 +2031,9 @@ linkend="collaborative-maint"/> ). Unless you know the maintainer is still active, it is wise to check the package to see if it has been orphaned. The current list of orphaned packages which haven't had their maintainer set correctly is available at . If you perform an NMU on an +url="&url-debian-qa-orphaned;">. If you perform an NMU on an improperly orphaned package, please set the maintainer to ``Debian QA Group -<packages@qa.debian.org>''. +<&pts-host;>''. @@ -2122,7 +2124,7 @@ Add the co-maintainer's correct maintainer name and address to the debian/control file. -: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> +Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org> @@ -2236,7 +2238,7 @@ all the necessary criteria); To find out whether a package is progressing into testing or not, see the testing script output on the web page of the testing +url="&url-devel-docs;testing">web page of the testing distribution, or use the program grep-excuses which is in the devscripts package. This utility can easily be used in a @@ -2248,7 +2250,7 @@ to keep yourself informed of the progression of your packages into The update_excuses file does not always give the precise reason why the package is refused; you may have to find it on your own by looking for what would break with the inclusion of the package. The testing web page gives some +url="&url-devel-docs;testing">testing web page gives some more information about the usual problems which may be causing such troubles. @@ -2401,7 +2403,7 @@ considered for update. Currently, this requires some manual hinting from the release team. Please -contact them by sending mail to debian-release@lists.debian.org +contact them by sending mail to debian-release@&lists-host; if this happens to one of your packages. @@ -2449,14 +2451,14 @@ so important for you.) If you want to see more details, you can look it up on -merkel:/org/ftp.debian.org/testing/update_out/ (or there in +merkel:/org/&ftp-debian-org;/testing/update_out/ (or there in ~aba/testing/update_out to see a setup with a smaller packages file). Via web, it's at +url="http://&ftp-master-host;/testing/update_out_code/"> The hints are available via . +url="http://&ftp-master-host;/testing/hints/">. @@ -2475,7 +2477,7 @@ Keep in mind that packages uploaded there are not automatically processed, they have to go through the hands of the release manager. So you'd better have a good reason to upload there. In order to know what a good reason is in the release managers' eyes, you should read the instructions that they regularly -give on debian-devel-announce@lists.debian.org. +give on debian-devel-announce@&lists-host;. You should not upload to testing-proposed-updates when you @@ -2533,7 +2535,7 @@ and lower than in unstable; After uploading and successful build on all platforms, contact the release team -at debian-release@lists.debian.org and ask them to approve your +at debian-release@&lists-host; and ask them to approve your upload. diff --git a/resources.dbk b/resources.dbk index cc04f3d..373bc55 100644 --- a/resources.dbk +++ b/resources.dbk @@ -1,6 +1,8 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Resources for Debian Developers @@ -13,11 +15,11 @@ all the other resources that are available to help you in your maintainer work. Much of the conversation between Debian developers (and users) is managed through a wide array of mailing lists we host at lists.debian.org. To find out +url="http://&lists-host;/">&lists-host;. To find out more on how to subscribe or unsubscribe, how to post and how not to post, where to find old posts and how to search them, how to contact the list maintainers and see various other information about the mailing lists, please read . This section will only +url="&url-debian-lists;">. This section will only cover aspects of mailing lists that are of particular interest to developers.
@@ -35,7 +37,7 @@ In general, please adhere to the usual conventions for posting messages. Please read the code of conduct +url="&url-debian-lists;#codeofconduct">code of conduct for more information.
@@ -48,52 +50,52 @@ The core Debian mailing lists that developers should use are: -debian-devel-announce@lists.debian.org, used to announce +debian-devel-announce@&lists-host;, used to announce important things to developers. All developers are expected to be subscribed to this list. -debian-devel@lists.debian.org, used to discuss various +debian-devel@&lists-host;, used to discuss various development related technical issues. -debian-policy@lists.debian.org, where the Debian Policy is +debian-policy@&lists-host;, where the Debian Policy is discussed and voted on. -debian-project@lists.debian.org, used to discuss various +debian-project@&lists-host;, used to discuss various non-technical issues related to the project. There are other mailing lists available for a variety of special topics; see - for a list. + for a list.
Special lists -debian-private@lists.debian.org is a special mailing list for +debian-private@&lists-host; is a special mailing list for private discussions amongst Debian developers. It is meant to be used for posts which for whatever reason should not be published publicly. As such, it is a low volume list, and users are urged not to use -debian-private@lists.debian.org unless it is really necessary. +debian-private@&lists-host; unless it is really necessary. Moreover, do not forward email from that list to anyone. Archives of this list are not available on the web for obvious reasons, but you -can see them using your shell account on lists.debian.org -and looking in the ~debian/archive/debian-private +can see them using your shell account on &lists-host; +and looking in the &file-debian-private-archive; directory. -debian-email@lists.debian.org is a special mailing list used as +debian-email@&lists-host; is a special mailing list used as a grab-bag for Debian related correspondence such as contacting upstream authors about licenses, bugs, etc. or discussing the project with others where it might be useful to have the discussion archived somewhere. @@ -111,9 +113,9 @@ a self-managed mailing list on Alioth is more appropriate. -If you decide that a regular mailing list on lists.debian.org is really what +If you decide that a regular mailing list on &lists-host; is really what you want, go ahead and fill in a request, following the HOWTO. +url="&url-debian-lists-new;">the HOWTO.
@@ -146,10 +148,10 @@ information for developers. Since #debian-devel is an open channel, you should not speak there of issues that are discussed in -debian-private@lists.debian.org. There's another channel for +debian-private@&lists-host;. There's another channel for this purpose, it's called #debian-private and it's protected by a key. This key is available in the archives of debian-private in -master.debian.org:~debian/archive/debian-private/, just +master.debian.org:&file-debian-private-archive;, just zgrep for #debian-private in all the files. @@ -191,7 +193,7 @@ documentation for more information about cloaks. This document contains a lot of information which is useful to Debian developers, but it cannot contain everything. Most of the other interesting -documents are linked from The +documents are linked from The Developers' Corner. Take the time to browse all the links, you will learn many more things. @@ -207,7 +209,7 @@ activities, and they all have a permanent connection to the Internet. Most of the machines are available for individual developers to use, as long as the developers follow the rules set forth in the Debian Machine Usage Policies. +url="&url-devel-docs;dmup">Debian Machine Usage Policies. Generally speaking, you can use these machines for Debian-related purposes as @@ -227,7 +229,7 @@ servers, unless you have prior permission. The current list of Debian machines is available at . That web page contains +url="&url-devel-machines;">. That web page contains machine names, contact information, information about who can log in, SSH keys etc. @@ -235,7 +237,7 @@ etc. If you have a problem with the operation of a Debian server, and you think that the system operators need to be notified of this problem, the Debian system administrator team is reachable at -debian-admin@lists.debian.org. +debian-admin@&lists-host;. If you have a problem with a certain service, not related to the system @@ -251,7 +253,7 @@ mirrored to another server.
The bugs server -bugs.debian.org is the canonical location for the Bug +&bugs-host; is the canonical location for the Bug Tracking System (BTS). @@ -260,7 +262,7 @@ It is restricted; a mirror is available on merkel. If you plan on doing some statistical analysis or processing of Debian bugs, this would be the place to do it. Please describe your plans on -debian-devel@lists.debian.org before implementing anything, +debian-devel@&lists-host; before implementing anything, however, to reduce unnecessary duplication of effort or wasted processing time.
@@ -268,7 +270,7 @@ however, to reduce unnecessary duplication of effort or wasted processing time.
The ftp-master server -The ftp-master.debian.org server holds the canonical copy of +The &ftp-master-host; server holds the canonical copy of the Debian archive (excluding the non-US packages). Generally, package uploads go to this server; see . @@ -277,7 +279,7 @@ It is restricted; a mirror is available on merkel. Problems with the Debian FTP archive generally need to be reported as bugs -against the ftp.debian.org +against the &ftp-debian-org; pseudo-package or an email to ftpmaster@debian.org, but also see the procedures in . @@ -286,7 +288,7 @@ the procedures in .
The non-US server -The non-US server non-us.debian.org was discontinued with +The non-US server &non-us-host; was discontinued with the release of sarge. The pseudo-package nonus.debian.org still exists for now. @@ -301,9 +303,9 @@ official web pages, the face of Debian for most newbies. If you find a problem with the Debian web server, you should generally submit a bug against the pseudo-package, www.debian.org. Remember to check whether or not +role="package">&www-debian-org;. Remember to check whether or not someone else has already reported the problem to the Bug Tracking System. +url="http://&bugs-host;/&www-debian-org;">Bug Tracking System.
@@ -330,7 +332,7 @@ materials subject to the U.S. export restrictions, in which case you can use one of the other servers located outside the United States. -Send mail to debian-devel@lists.debian.org if you have any +Send mail to debian-devel@&lists-host; if you have any questions.
@@ -350,7 +352,7 @@ a CVS area on the server. Generally, cvs.debian.org offers a combination of local CVS access, anonymous client-server read-only access, and full client-server access through ssh. Also, the CVS area can be accessed read-only -via the Web at . +via the Web at . To request a CVS area, send a request via email to @@ -367,13 +369,13 @@ On some machines, there are chroots to different distributions available. You can use them like this: -% dchroot unstable +vore$ dchroot unstable Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable In all chroots, the normal user home directories are available. You can find out which chroots are available via -http://db.debian.org/machines.cgi. +&url-devel-machines;. @@ -382,14 +384,14 @@ out which chroots are available via
The Developers Database -The Developers Database, at , is an +The Developers Database, at , is an LDAP directory for managing Debian developer attributes. You can use this resource to search the list of Debian developers. Part of this information is also available through the finger service on Debian servers, try finger yourlogin@db.debian.org to see what it reports. -Developers can log into the +Developers can log into the database to change various information about themselves, such as: @@ -412,7 +414,7 @@ whether you are on vacation personal information such as your address, country, the latitude and longitude of the place where you live for use in the world map of Debian +url="&url-devel-docs;developers.loc">the world map of Debian developers, phone and fax numbers, IRC nickname and web page @@ -425,86 +427,27 @@ password and preferred shell on Debian Project machines Most of the information is not accessible to the public, naturally. For more information please read the online documentation that you can find at . +url="&url-debian-db-doc;">. Developers can also submit their SSH keys to be used for authorization on the official Debian machines, and even add new *.debian.net DNS entries. Those features are documented at . +url="&url-debian-db-mail-gw;">.
The Debian archive -The Debian GNU/Linux distribution consists of a lot of packages -(.deb's, currently around 9000) and a few additional files +The &debian-formal; distribution consists of a lot of packages +(.deb's, currently around &number-of-pkgs;) and a few additional files (such as documentation and installation disk images). Here is an example directory tree of a complete Debian archive: - -/stable/main/ -dists/stable/main/binary-i386/ -dists/stable/main/binary-m68k/ -dists/stable/main/binary-alpha/ - ... -dists/stable/main/source/ - ... -dists/stable/main/disks-i386/ -dists/stable/main/disks-m68k/ -dists/stable/main/disks-alpha/ - ... - -dists/stable/contrib/ -dists/stable/contrib/binary-i386/ -dists/stable/contrib/binary-m68k/ -dists/stable/contrib/binary-alpha/ - ... -dists/stable/contrib/source/ - -dists/stable/non-free/ -dists/stable/non-free/binary-i386/ -dists/stable/non-free/binary-m68k/ -dists/stable/non-free/binary-alpha/ - ... -dists/stable/non-free/source/ - -dists/testing/ -dists/testing/main/ - ... -dists/testing/contrib/ - ... -dists/testing/non-free/ - ... - -dists/unstable -dists/unstable/main/ - ... -dists/unstable/contrib/ - ... -dists/unstable/non-free/ - ... - -pool/ -pool/main/a/ -pool/main/a/apt/ - ... -pool/main/b/ -pool/main/b/bash/ - ... -pool/main/liba/ -pool/main/liba/libalias-perl/ - ... -pool/main/m/ -pool/main/m/mailx/ - ... -pool/non-free/n/ -pool/non-free/n/netscape/ - ... - +&sample-dist-dirtree; As you can see, the top-level directory contains two directories, dists/ and pool/. The latter is a @@ -539,17 +482,17 @@ installing the Debian distribution on a specific architecture Sections The main section of the Debian archive is what makes up -the official Debian GNU/Linux distribution. +the official &debian-formal; distribution. The main section is official because it fully complies with all our guidelines. The other two sections do not, to different degrees; as such, they are not officially part of -Debian GNU/Linux. +&debian-formal;. Every package in the main section must fully comply with the Debian Free Software +url="&url-dfsg;">Debian Free Software Guidelines (DFSG) and with all other policy requirements as described -in the Debian Policy +in the Debian Policy Manual. The DFSG is our definition of “free software.” Check out the Debian Policy Manual for details. @@ -566,7 +509,7 @@ infrastructure (such as our bug-tracking system and mailing lists) for non-free software packages. -The Debian Policy +The Debian Policy Manual contains a more exact definition of the three sections. The above discussion is just an introduction. @@ -616,7 +559,7 @@ is m68k, alpha, mipsel and sh as of this writing. -Debian GNU/Linux 1.3 is only available as i386. Debian +&debian-formal; 1.3 is only available as i386. Debian 2.0 shipped for i386 and m68k architectures. Debian 2.1 ships for the i386, m68k, alpha, and @@ -628,7 +571,7 @@ and mipsel. Information for developers and users about the specific ports are available at -the Debian Ports web pages. +the Debian Ports web pages.
@@ -724,7 +667,7 @@ the Release Team, the distribution is released. Releasing means that new copy is created for the new testing, and the previous stable is renamed to oldstable and stays there until it is finally archived. On archiving, the contents are moved -to archive.debian.org). +to &archive-host;). This development cycle is based on the assumption that the @@ -780,10 +723,10 @@ These are the sources.list 5 lines for experimental: - - http://ftp.xy.debian.org/debian/ experimental main + +deb http://ftp.xy.debian.org/debian/ experimental main deb-src http://ftp.xy.debian.org/debian/ experimental main - + If there is a chance that the software could do grave damage to a system, it is likely to be better to put it into experimental. For @@ -888,7 +831,7 @@ push mirroring). All the information on Debian mirrors, including a list of the available public FTP/HTTP servers, can be found at . This useful page also includes +url="url-debian-mirroring">. This useful page also includes information and tools which can be helpful if you are interested in setting up your own mirror, either for internal or public access. @@ -904,7 +847,7 @@ 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 on ftp-master.debian.org. +scripts that are installed on &ftp-master-host;. Packages are uploaded by all the maintainers into a directory called @@ -942,14 +885,14 @@ The archive maintenance software will also send the OpenPGP/GnuPG signed .changes file that you uploaded to the appropriate mailing lists. If a package is released with the Distribution: set to `stable', the announcement is sent to -debian-changes@lists.debian.org. If a package is released with +debian-changes@&lists-host;. If a package is released with Distribution: set to `unstable' or `experimental', the announcement will be posted to -debian-devel-changes@lists.debian.org instead. +debian-devel-changes@&lists-host; instead. Though ftp-master is restricted, a copy of the installation is available to all -developers on merkel.debian.org. +developers on &ftp-master-mirror;.