Inhaltsverzeichnis
debian/rulesdebian/controldebian/changelogdebconf.orig.tar.{gz,bz2,xz}-DateienDebians Qualität ist größtenteils den Debian-Richtlinien zu verdanken, die explizit grundlegende Anforderungen definieren, die alle Debian-Pakete erfüllen müssen. Bisher gibt es außerdem eine gemeinsame Geschichte der Erfahrung, die hinter den Debian-Richtlinien steckt, einer Ansammlung jahrelanger Erfahrung im Paketieren. Viele sehr talentierte Leute haben großartige Werkzeuge geschaffen, Werkzeuge, die Ihnen als Debian-Betreuer helfen, ausgezeichnete Pakete zu erstellen und zu pflegen.
Dieses Kapitel stellt einige optimale Vorgehensweisen für Debian-Entwickler vor. Das alles sind lediglich Empfehlungen und keine Anforderungen oder Richtlinien. Dies sind nur einige subjektive Hinweise, Ratschläge und Fingerzeige, die von Debian-Entwicklern gesammelt wurden. Suchen Sie sich einfach das heraus, was Ihnen am meisten zusagt.
Die folgenden Empfehlungen gelten für die Datei
debian/rules. Da debian/rules den
Build-Prozess steuert und die Dateien auswählt, die in das Paket gelangen
(direkt oder indirekt), ist es normerweise die Datei, der die Betreuer die
meiste Zeit widmen.
Der Grund für die Benutzung von Helfer-Skripten in
debian/rules ist, dass sie den Betreuern eine geteilte
gemeinsame Logik inmitten vieler Pakete einräumen. Nehmen Sie zum Beispiel
die Frage, wie Menü-Einträge installiert werden: Sie müssen die Datei in
/usr/share/menu (oder
/usr/lib/menu für ausführbare binäre Menü-Dateien, wenn
nötig) ablegen und den Betreuerskripten Befehle hinzufügen, um Menü-Einträge
zu registrieren bzw. ihre Registrierung zu entfernen. Dies ist eine sehr
häufige Tätigkeit für Pakete. Warum sollte daher jeder Betreuer all dies für
sich selbst neu schreiben und dabei möglicherweise Fehler verursachen?
Außerdem, den Fall gesetzt, das Menü-Verzeichnis würde sich ändern, dann
müsste jedes Paket geändert werden.
Helfer-Skripte kümmern sich um diese Probleme. Angenommen, Sie erfüllen alle Gepflogenheiten, die das Helfer-Skript erwartet, dann kümmert sich das Helfer-Skript um alle Einzelheiten. Änderungen an den Richtlinien können im Helfer-Skript erledigt werden. Dann müssen Pakete nur mit der neuen Version des Helfer-Skripts erstellt und sonst nicht geändert werden.
Anhang A, Überblick über die Werkzeuge der Debian-Betreuer enthält ein paar verschiedene Helfer-Skripte. Das
gängigste und beste (nach Meinung von Debian) Helfersystem ist debhelper. Verhergehende Helfersysteme, wie
debmake waren monolithisch. Sie
konnten nicht den Teil des Helfers herausgreifen und auswählen, den Sie
nützlich fanden, mussten aber den Helfer für alles benutzen. debhelper besteht jedoch aus mehreren getrennten
kleinen dh_*-Programmen. dh_installman
installiert und komprimiert zum Beispiel Handbuchseiten,
dh_installmenu installiert Menü-Dateien und so
weiter. Daher bietet es eine ausreichende Flexibilität, die kleinen
Helfer-Skripte dort zu benutzen, wo sie nützlich sind in Verbindung mit
handgemachten Befehlen in debian/rules.
Sie können mit debhelper anfangen,
indem Sie debhelper(1) lesen und sich die Beispiele
ansehen, die dem Paket beigefügt sind. dh_make aus dem
Paket dh-make (siehe Abschnitt A.3.2, „dh-make“) kann benutzt werden, um ein einfaches Quellpaket in ein
mit debhelper bearbeitetes Paket
umzuwandeln. Gleichwohl sollte diese Kurzform Sie jedoch nicht davon
überzeugen, dass Sie sich nicht plagen müssen, um die einzelnen
dh_*-Helfer zu verstehen. Falls Sie einen Helfer benutzen
möchten, müssen Sie sich die Zeit nehmen zu lernen, wie dieser Helfer
benutzt wird, um zu verstehen was er erwartet und wie er sich verhält.
Große, komplexe Pakete könnten mehrere Fehler haben, die Sie bewältigen
müssen. Falls Sie mehrere Fehler direkt in der Quelle beheben und nicht
sorgfältig vorgehen, kann es schwierig werden, die verschiedenen Patchs, die
Sie bereitgestellt haben, zu unterscheiden. Es kann ziemlich chaotisch
werden, wenn Sie das Paket auf eine neue Originalversion aktualisieren
müssen, die einige (aber nicht alle) Reparaturen enthält. Sie können nicht
die komplette Zusammenstellung der Diffs nehmen (z.B. aus
.diff.gz) und austüfteln, welches Patch es als Einheit
zurücksetzt, da Fehler im Original repariert wurden.
Glücklicherweise ist es nun mit dem Quellformat »3.0 (quilt)« möglich, die
Patchs getrennt zu halten ohne debian/rules zur
Einrichtung eines Patch-Systems ändern zu müssen. Patchs werden in
debian/patches/ gespeichert und wenn das Quellpaket
entpackt wird, werden automatisch die Patchs angewandt, die in
debian/patches/series aufgeführt sind. Wie der Name
schon sagt, können Patchs mit quilt verwaltet werden.
Wenn Sie die ältere Quelle »1.0« verwenden, ist es auch möglich, Patchs zu
trennen, aber es muss ein zugehöriges Patch-System verwandt werden: Die
Patch-Dateien werden innerhalb der Debian-Patch-Datei
(.diff.gz) mitgeliefert, normalerweise im Verzeichnis
debian/. Der einzige Unterschied ist, dass sie nicht
unmittelbar von dpkg-source angewandt werden, sondern von
der build-Regel der Datei
debian/rules durch eine Abhängigkeit in der
patch-Regel. Im Gegenzug werden sie von der Regel
clean durch eine Abhängigkeit zur Regel
unpatch umgekehrt.
quilt ist das dafür empfohlene Werkzeug. Es erledigt
alles oben beschriebene und ermöglicht außerdem die Verwaltung von
Patch-Serien. Weitere Informationen finden Sie im Paket quilt.
Es gibt noch andere Werkzeuge, um Patchs zu verwalten, wie
dpatch und das in cdbs eingebaute Patch-System.
Ein einzelnes Quellpaket wird oft mehrere Binärpakete erstellen, entweder um
mehrere Geschmacksrichtungen der gleichen Software bereitzustellen (z.B. das
vim-Quellpaket) oder um mehrere
kleine Pakete anstelle eines einzelnen großen zu erzeugen (z,B. damit der
Benutzer nur die benötigte Untermenge installieren kann und dadurch
Plattenplatz spart).
Der zweite Fall kann einfach in debian/rules verwaltet
werden. Sie müssen nur die entsprechenden Dateien aus dem Build-Verzeichnis
in die entsprechenden temporären Baumstrukturen des Pakets verschieben. Dies
können Sie mit install oder dh_install
aus debhelper erledigen. Sorgen Sie
dafür, dass Sie die unterschiedlichen Umsetzungen der verschiedenen Pakete
prüfen, um sicherzustellen, dass Sie die wechselseitigen Abhängigkeiten in
debian/control richtig gesetzt haben.
Der erste Fall ist etwas schwieriger, da er mehrmaliges Neukompilieren der
selben Software einschließt, aber mit unterschiedlichen
Konfigurationsoptionen. Das vim-Quellpaket ist ein Beispiel dafür, wie dies
mit einer handgemachten debian/rules-Datei verwaltet
wird.
Die folgenden Vorgehensweisen sind maßgeblich für die Datei
debian/control. Sie ergänzen die Richtlinien für
Paketbeschreibungen.
Die Beschreibung des Pakets, wie sie durch das entsprechende Feld in der
Datei control definiert wird, enthält sowohl die
Paketübersicht, als auch die ausführliche Beschreibung des Pakets. Abschnitt 6.2.1, „Allgemeine Richtlinien für Paketbeschreibungen“ beschreibt übliche Richtlinien für beide Teile
der Paketbeschreibung. Diesen folgend stellt Abschnitt 6.2.2, „Die Paketübersicht oder Kurzbeschreibung“ Richtlinien speziell für die Übersicht bereit
und Abschnitt 6.2.3, „Die ausführliche Beschreibung“ enthält spezielle Richtlinien für die
Beschreibung.
Die Paketbeschreibung sollte für den erwarteten Durchschnittsanwender geschrieben werden, der Durchschnittsperson, die das Paket benutzt und davon profitiert. Entwicklungspakete sind beispielsweise für Entwickler und können in einer technischen Sprache verfasst werden. Anwendungen für allgemeinere Zwecke, wie Editoren, sollten für Anwender mit weniger technischem Verständnis geschrieben werden.
Die Durchsicht der Paketbeschreibungen mündet in der Schlussfolgerung, dass die meisten Paketbeschreibungen technischer Natur sind, also nicht so geschrieben, das sie für Anwender ohne technischen Hintergrund einen Sinn ergeben. Sofern Ihr Paket nicht wirklich für technikkundige Anwender ist, ist dies ein Problem.
Wie können sie für nicht technikkundige Anwender schreiben? Vermeiden Sie Fachsprache. Vermeiden Sie, sich auf Anwendungen und Rahmenwerke zu beziehen, mit denen der Anwender möglicherweise nicht vertraut ist – GNOME oder KDE sind in Ordnung, da Anwender wahrscheinlich mit diesen Begriffen vertraut sind, aber GTK+ vermutlich nicht. Versuchen Sie nicht irgendein Wissen vorauszusetzen, geben Sie eine Einführung.
Seien Sie objektiv. Paketbeschreibungen sind nicht der richtige Ort, um Ihr Paket zu verfechten, egal wie sehr Sie es mögen. Denken Sie daran, dass der Leser nicht die gleichen Dinge wichtig nimmt, wie Sie.
Bezüge zu Namen anderer Softwarepakete, Protokollnamen, Standards oder Spezifikationen sollten, falls sie existiert, in ihrer vorschriftsmäßigen Form verwandt werden. Benutzen Sie zum Beispiel X Window System, X11 oder X, nicht X Windows, X-Windows, or X Window. Benutzen Sie GTK+, nicht GTK oder gtk. Benutzen Sie GNOME nicht Gnome. Benutzen Sie PostScript, nicht Postscript oder postscript.
Falls Sie Probleme beim Verfassen Ihrer Beschreibung haben, könnten Sie sie
an <debian-l10n-english@lists.debian.org> senden und um Rückmeldung ersuchen.
Die Richtlinie sagt, die Übersichtszeile (die Kurzbeschreibung) muss kurz sein, darf den Paketnamen nicht wiederholen, muss aber auch informativ sein.
Die Übersichtsfunktionen sind ein Ausdruck, der das Paket beschreibt, kein kompletter Satz, daher ist Zeichensetzung unangebracht: Es wird weder eine besondere Großschreibung noch ein abschließender Punkt benötigt. Außerdem sollten jegliche bestimmten und unbestimmten Artikel am Anfang weggelassen werden – »a«, »an« oder »the«. Deshalb zum Beispiel:
Package: libeg0 Description: exemplification support library
Technisch gesehen ist dies eine Nominalphrase im Gegensatz zu einer
Verbalphrase. Eine gute Entscheidungsregel ist, dass es möglich sein sollte,
den Paket-Namen und die
Übersicht in diesem Schema zu ersetzen:
The package Name provides {a,an,the,some}
Übersicht.
Zusammenstellungen verwandter Pakete können ein alternatives Schema benutzen, das die Übersicht in zwei Teile unterteilt, als erstes eine Beschreibung der ganzen Suite und als zweites eine Zusammenfassung der Rolle, die das Paket darin spielt:
Package: eg-tools Description: simple exemplification system (utilities) Package: eg-doc Description: simple exemplification system - documentation
Diese Übersicht folgt einem geänderten Schema. Wo ein Paket
»Name« die Übersicht
»Suite (Rolle)« oder
»Suite - Rolle« hat,
sollten die Elemente so ausgedrückt werden, dass sie in dieses Schema
passen:
The package name provides {a,an,the}
role for the suite.
Die ausführliche Beschreibung ist die wichtigste für den Benutzer verfügbare Information über ein Paket, bevor er es installiert. Sie sollte alle nötigen Informationen bereitstellen, damit der Anwender entscheiden kann, ob er das Paket installiert. Es ist anzunehmen, dass der Benutzer bereits die Paketübersicht gelesen hat.
Die ausführliche Beschreibung sollte aus vollständigen Sätzen bestehen.
Der erste Absatz der ausführlichen Beschreibung sollte die folgenden Fragen beantworten: Was tut das Paket? Bei welchen Aufgaben hilft es dem Anwender? Es ist wichtig dies auf eine nicht technische Weise zu beschreiben, sogar dann, wenn die Zielgruppe des Pakets notwendigerweise einen technischen Hintergrund hat.
Die folgenden Absätze sollten die folgenden Fragen beantworten: Warum benötige ich als Benutzer dieses Paket? Welche anderen Funktionen bietet das Paket? Welche herausragenden Funktionen und Mängel gibt es im Vergleich zu anderen Paketen (z.B. falls Sie X benötigen, benutzen Sie Y)? Steht das Paket in einem Zusammenhang mit anderen Paketen, die nicht vom Paketmanager gehandhabt werden (z.B. ist dies der Client für den Foo-Server)?
Seien Sie vorsichtig, um Rechtschreib- und Grammatikfehler zu
vermeiden. Sorgen Sie für eine Rechtschreibprüfung. Sowohl
ispell als auch aspell haben spezielle
Modi zur Prüfung von debian/control-Dateien:
ispell -d american -g debian/control
aspell -d en -D -c debian/control
Anwender erwarten normalerweise, dass diese Fragen in der Paketbeschreibung beantwortet werden:
Was tut das Paket? Falls es eine Erweiterung eines anderen Pakets ist, dann sollte eines Kurzbeschreibung des Pakets, das es erweitert, hier eingefügt werden.
Warum sollte ich dieses Paket wollen? Dies bezieht sich auf das vorhergehende, aber nicht das gleiche (dies ist ein Mail-Client. Er ist toll, schnell, hat Schnittstellen zu PGP, LDAP und IMAP, hat die Funktionen X, Y und Z).
Falls dieses Paket nicht direkt installiert werden sollte, sondern von einem anderen Paket mitinstalliert wird, sollte die erwähnt werden.
Falls das Paket experimental ist oder es andere Gründe
gibt, weshalb es nicht benutzt werden sollte und wenn es andere Pakete gibt,
die stattdessen benutzt werden sollen, sollte dies auch hier stehen.
Was unterscheidet dieses Paket von der Konkurrenz? Ist es eine bessere Implementierung? Mehr Funktionen? Andere Funktionen? Warum sollte die Wahl auf dieses Paket fallen?
Es wird empfohlen, dass Sie die URL der Homepage des Pakets in das Feld
Homepage im Abschnitt Source von
debian/control hinzufügen. Diese Information in die
Paketbeschreibung selbst einzutragen, wird als missbilligt angesehen.
Es gibt zusätzliche Felder für den Ort des Versionsverwaltungssystems in
debian/control.
Der Wert dieses Feldes sollte eine http://-URL sein, die
auf eine via Web durchstöberbare Kopie des Versionsverwaltungssystems-Depots
verweist, das benutzt wird, um das angegebene Paket zu verwalten, falls
verfügbar.
Die Information ist dazu gedacht, dem Endanwender zu nutzen, der gewillt
ist, die letzte am Paket geleistete Arbeit zu durchstöbern (z.B. wenn nach
einem Patch gesucht wird, der einen Fehler behebt, der in der
Fehlerdatenbank als pending gekennzeichnet ist).
Der Wert dieses Feldes sollte eine Zeichenkette sein, die den Ort des
Versionsverwaltungssystem-Depots eindeutig identifiziert, das zur Verwaltung
des angegebenen Pakets benutzt wird, falls verfügbar. *
identifiziert das Versionsverwaltungssystem. Aktuell werden die folgenden
vom Paketverfolgungssystem unterstützt: arch,
bzr (Bazaar), cvs,
darcs, git, hg
(Mercurial), mtn (Monotone) und svn
(Subversion). Es ist erlaubt, mehrere unterschiedliche
Versionsverwaltungssystem-Felder für das gleiche Paket anzugeben: Sie werden
alle auf der PTS-Web-Schnittstelle angezeigt.
Die Information ist für Benutzer bestimmt, die im gegebenen Versionsverwaltungssystem sachkundig sind und bereit, die aktuelle Version des Pakets aus den VCS-Quellen zu erstellen. Andere Nutzungen dieser Information könnten das automatische Erstellen der letzen VCS-Version des Pakets umfassen. Dazu sollte der vom Feld angegebene Ort, die Version nicht kennen und auf den Hauptzweig zeigen (bei Versionsverwaltungssystemen, die dieses Konzept unterstützen). Außerdem sollte der Endanwender auf den Ort, auf den verwiesen wird, zugreifen können. Die Erfüllung dieser Anforderungen könnte einen anonymen Zugriff voraussetzen, statt auf eine Version davon zu verweisen, auf die über SSH zugegriffen wird.
Im folgenden Beispiel wird ein Fall von einem Feld eines Subversions-Depots
des Pakets vim gezeigt. Beachten
Sie, wie die URL im svn://-Schema aufgebaut ist (im
Gegensatz zu svn+ssh://) und wie sie auf den Zweig
trunk/ zeigt. Außerdem wird die Benutzung der Felder
Vcs-Browser und Homepage, wie oben
beschrieben, ebenfalls gezeigt.
Source: vim Section: editors Priority: optional <snip> Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim Homepage: http://www.vim.org
Die folgenden Vorgehensweisen ergänzen die Richtlinien für Änderungsprotokolldateien.
Der Änderungsprotokolleintrag einer Paketüberarbeitung dokumentiert Änderungen in nur dieser Überarbeitung. Der Schwerpunkt liegt auf der Beschreibung bedeutender und für den Anwender sichtbarer Änderungen, die seit der letzten Version vorgenommen wurden.
Der Fokus liegt darauf, was geändert wurde – wer, wie und wann ist normalerweise nicht so wichtig. Erinnern Sie gleichwohl höflich an die Leute, die merklich Hilfe beim Erstellen des Pakets geleistet haben (die z.B. Patchs gesandt haben).
Es ist nicht nötig, die belanglosen und offensichtlichen Änderungen näher
auszuführen. Sie können außerdem mehrere Änderungen in einem Eintrag
zusammenfassen. Fassen Sie sich andererseits nicht zu kurz, falls Sie eine
größere Änderung vorgenommen haben. Stellen Sie insbesondere klar, falls es
Änderungen gibt, die das Verhalten des Programms ändern. Benutzen Sie für
weitere Erklärungen die Datei README.Debian.
Benutzen Sie geläufiges Englisch, so dass die Mehrheit der Leser es begreifen kann. Vermeiden Sie Abkürzungen, technische Begriffe und Fachsprache, wenn Sie Änderungen erklären, die Fehlerberichte schließen, insbesondere bei Fehlern, die von Anwendern eingereicht wurden, die Ihnen als technisch unerfahren aufgefallen sind. Seien Sie höflich, fluchen Sie nicht.
Manchmal ist es wünschenswert, den Änderungsprotokolleinträgen die Namen der Dateien voranzustellen, die geändert wurden. Es ist jedoch nicht nötig, explizit jede einzelne geänderte Datei aufzuführen, insbesondere dann nicht, wenn die Änderung klein oder wiederholend war. Sie können Platzhalter verwenden.
Treffen Sie keine Annahmen, wenn Sie sich auf Fehler beziehen. Sagen Sie, welches Problem vorlag, wie es behoben wurde und hängen Sie die Zeichenkette »closes: #nnnnn« an. Weitere Informationen erhalten Sie unter Abschnitt 5.8.4, „Wann Fehler durch neue Uploads geschlossen werden“.
Die Änderungsprotokolleinträge sollten keine allgemeinen Paketierungsthemen dokumentieren (Hey, falls Sie die Foo.conf suchen, die ist in /etc/blah/.), da von Administratoren und Anwendern angenommen wird, dass sie zumindest entfernt damit vertraut sind, wie solche Dinge im Allgemeinen auf Debian-Systemen eingerichtet sind. Erwähnen Sie jedoch, wenn Sie den Ort einer Konfigurationsdatei ändern.
Die einzigen Fehler, die mit einem Änderungsprotokolleintrag geschlossen werden, sollten Fehler sein, die tatsächlich in der gleichen Überarbeitung des Pakets behoben werden. Das Schließen von Fehlern ohne Bezug dazu, ist eine falsche Vorgehensweise. Siehe Abschnitt 5.8.4, „Wann Fehler durch neue Uploads geschlossen werden“.
Die Änderungsprotokolleinträge sollten nicht für zufällige Diskussionen mit Leuten, die Fehler melden (Ich kann keine Schutzverletzungen sehen, wenn ich Foo mit der Option Bar starte. Senden Sie weitere Informationen.), allgemeine Äußerungen über das Leben, das Universum und alles mögliche (Entschuldigung, dass der Upload so lange brauchte, aber ich hatte die Grippe.) oder Hilfeersuchen (Die Fehlerliste für dieses Paket ist riesig, bitte packen Sie mit an) benutzt werden. Solche Dinge werden normalerweise nicht von Ihrer Zielgruppe bemerkt, könnten aber viele Leute stören, die Informationen über tatsächliche Änderungen am Paket lesen möchten. Weitere Informationen über die Benutzung der Fehlerdatenbank finden Sie unter Abschnitt 5.8.2, „Auf Fehler antworten“.
Es ist ein alter Brauch im ersten regulären Upload des Paketbetreuers das Beheben von Fehlern durch Non-Maintainer-Uploads zu bestätigen. Da Debian nun über eine Versionsverwaltung verfügt, reicht es aus, die NMU-Änderungsprotokolleinträge aufzubewahren und diese Tatsache nur in Ihrem eigenen Änderungsprotokolleintrag zu erwähnen.
Die folgenden Beispiele demonstrieren einige häufige Fehler oder Beispiele für schlechten Stil in Änderungsprotokolleinträgen.
* Fixed all outstanding bugs.
Dies teilt den Lesern offensichtlich nichts Nützliches mit.
* Applied patch from Jane Random.
Was war das für ein Patch?
* Late night install target overhaul.
Welche Reparatur wurde ausgeführt? Soll die Erwähnung der späten Nacht daran erinnern, dass man dem Code nicht trauen sollte?
* Fix vsync FU w/ ancient CRTs.
Zu viele Abkürzungen und es ist nicht klar, wovon der äh ... Mist (Hoppla, ein Schimpfwort) tatsächlich handelt oder wie er repariert wurde.
* This is not a bug, closes: #nnnnnn.
Erst einmal ist es absolut unnötig, das Paket hochzuladen, um diese Information zu übermitteln. Benutzen Sie stattdessen die Fehlerdatenbank. Zweitens fehlt die Erklärung, warum dieser Bericht kein Fehler ist.
* Has been fixed for ages, but I forgot to close; closes: #54321.
Falls Sie aus irgend einem Grund die Fehlernummer in einem früheren Änderungsprotokolleintrag nicht erwähnt haben, ist das kein Problem. Schließen Sie den Fehler einfach im BTS. Es ist nicht nötig, die Änderungsprotokolldatei anzurühren, vorausgesetzt, die Beschreibung der Fehlerbehebung ist bereits darin enthalten (Dies gilt auch für Reparaturen durch die Originalautoren/-Betreuer. Sie müssen keine Fehler verfolgen, die diese bereits vor Jahren in Ihrem Änderungsprotokoll behoben haben).
* Closes: #12345, #12346, #15432
Wo ist die Beschreibung? Falls Ihnen keine aussagekräftige Nachricht einfällt, beginnen Sie, die Titel der verschiedenen Fehler einzufügen.
Wichtige Nachrichten über Änderungen in einem Paket können auch in die
NEWS.Debian-Dateien geschrieben werden. Die Nachrichten
werden durch Werkzeuge wie apt-listchanges vor dem ganzen Rest des
Änderungsprotokolls angezeigt. Dies ist das vorzugsweise Mittel, dem
Anwender bedeutende Änderungen in einem Paket mitzuteilen. Es ist besser,
als debconf-Notizen zu benutzen, da
es weniger stört und der Anwender nach der Installation zurückgehen und in
der NEWS.Debian-Datei nachschlagen kann. Es ist auch
besser, als die Hauptänderungen in README.Debian
aufzuführen, da der Anwender solche Notizen leicht übersehen kann.
Das Dateiformat entspricht dem des Änderungsprotokolls, die Sternchen werden
allerdings weggelassen und jedes Nachrichtenelement wird, wenn nötig, mit
einem vollständigen Satz beschrieben, statt der kurz gefassten
Zusammenfassungen, die in ein Änderungsprotokoll einfließen. Sie sind gut
beraten, Ihre Datei durch dpkg-parsechangelog laufen zu
lassen, um ihre Formatierung zu prüfen, da sie nicht automatisch während des
Builds getestet wird, so wie dies beim Änderungsprotokoll getan wird. Hier
nun ein Beispiel einer echten NEWS.Debian-Datei:
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
functionality provided with that script, please install the new
package.
-- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
Die Datei NEWS.Debian wird als
/usr/share/doc/
installiert. Sie ist komprimiert und hat immer diesen Namen, auch in nativen
Debian-Paketen. Falls Sie Paket/NEWS.Debian.gzdebhelper benutzen, wird
dh_installchangelogs die
debian/NEWS-Dateien für Sie installieren.
Anders als Änderungsprotokolldateien, müssen Sie die
debian/NEWS-Dateien nicht bei jeder Veröffentlichung
aktualisieren. Aktualisieren Sie sie nur, wenn Sie etwas besonders
berichtenswertes haben, worüber der Anwender Bescheid wissen sollte. Falls
Sie überhaupt keine Nachrichten haben, ist es nicht nötig, Ihrem Paket eine
debian/NEWS-Datei mitzugeben. Keine Nachricht ist eine
gute Nachricht!
Betreuerskripte beinhalten die Dateien debian/postinst,
debian/preinst, debian/prerm und
debian/postrm. Diese Skripte geben auf jede
Installations- oder Deinstallationseinrichtung des Pakets acht, die bloß
durch Erstellen und Entfernen von Dateien und Verzeichnissen gehandhabt
wird. Die folgenden Anweisungen ergänzen die Debian Policy.
Betreuerskripte müssen Idempotent sein. Dies bedeuted, dass Sie sicherstellen müssen, dass nichts Schlimmes passiert, wenn das Skript zweimal aufgerufen wird, während es normalerweise einmal aufgerufen würde.
Standardein- und -ausgabe könnten zu Protokollierungszwecken umgeleitet werden (z.B. in Pipes), verlassen Sie sich daher nicht darauf, dass sie ein Terminal sind.
Jegliche Bedienerführung oder interaktive Konfiguration sollte so gering wie
möglich gehalten werden. Wenn es nötig ist, sollten Sie das Paket
debconf für die Schnittstelle
benutzen. Denken Sie daran, dass diese Bedienerführung nur in der
configure-Stufe des postinst-Skripts
stattfinden kann.
Halten Sie die Betreuerskripte so einfach wie möglich. Es wird empfohlen,
nur reine POSIX-Shell-Skripte zu benutzen. Falls Sie irgendwelche
Bash-Funktionen benötigen, vergessen Sie nicht, dass das Betreuerskript eine
Shebang-Zeile haben muss. POSIX-Shell oder Bash werden für Perl bevorzugt,
da sie debhelper ermöglichen, den
Skripten einfach Teile hinzuzufügen.
Falls Sie Ihre Betreuerskripte ändern, stellen Sie sicher, dass Sie das Entfernen des Pakets, die mehrmalige Installation und das vollständige Entfernen testen. Vergewissern Sie sich, dass nach dem vollständigen Entfernen des Pakets alles komplett weg ist, sprich, es muss jede erzeugte Datei entfernen, die direkt oder indirekt in irgendeinem Betreuerskript erstellt wurde.
Falls Sie prüfen möchten, ob ein Befehl existiert, sollten Sie so etwas benutzen:
if [ -x /usr/sbin/install-docs ]; then ...
Falls Sie nicht dem Pfad eines Befehls fest ins Betreuerskript schreiben möchten, könnte die folgende POSIX-konforme Shell-Funktion helfen:
pathfind() {
OLDIFS="$IFS"
IFS=:
for p in $PATH; do
if [ -x "$p/$*" ]; then
IFS="$OLDIFS"
return 0
fi
done
IFS="$OLDIFS"
return 1
}
Sie können diese Funktion benutzen, um $PATH nach einem
Befehlsnamen zu durchsuchen, der als Argument übergegeben wird. Sie gibt
»true« (null) zurück, falls der Befehl gefunden wurde und »false«, falls
nicht. Dies ist wirklich die portierbarste Möglichkeit, da command
-v, type und which nicht
POSIX-konform sind.
Obwohl which eine akzeptable Alternative ist, da es aus
dem benötigten Paket debianutils
stammt, liegt es nicht auf der Wurzel-Partition. Zumindest liegt es eher in
/usr/bin als in /bin, so dass es
nicht in Skripten benutzt werden kann, die vor dem Einhängen von
/usr ausgeführt werden. Dieses Problem werden
allerdings die meisten Skripte nicht haben.
Debconf ist ein
Konfigurationsverwaltungssystem, das von allerlei Paketierungsskripten
(hauptsächlich postinst) benutzt werden kann, um
Rückmeldungen von Anwendern betreffend der Paketkonfiguration
abzufragen. Direkte Benutzer-Interaktion muss nun zugunsten der Interaktion
mit debconf vermieden werden. Dies
wird in Zukunft nicht interaktive Installationen ermöglichen.
Debconf ist ein großartiges Werkzeug, aber es wird oft mangelhaft benutzt. Viele alltägliche Fehler sind auf der Handbuchseite debconf-devel(7) aufgeführt. Manchmal ist es nötig zu lesen, falls Sie sich entscheiden Debconf zu benutzen. Außerdem werden hier ein paar optimale Vorgehensweisen vorgestellt.
Diese Richtlinien enthalten einige Schreibstil- und Typografie-Empfehlungen, allgemeine Betrachtungen über die Benutzung von Debconf, ebenso wie spezifischere Empfehlungen für einige Teile der Distribution (das Installationssystem besispielsweise).
Seit Debconf in Debian erschien, wurde es verbreitet missbraucht und viel von der Kritik, die bei der Debian-Distribution einging, rührte vom Debconf-Missbrauch mit der Notwendigkeit, ein großes Fragenbündel zu beantworten, bevor eine Kleinigkeit installiert war.
Behalten Sie Aufrufnotizen dort, wozu sie gehören: den Dateien
NEWS.Debian oder
README.Debian. Benutzen Sie nur Notizen für wichtige
Anmerkungen, die direkt die Benutzbarkeit des Pakets beeinflussen. Bedenken
Sie, dass Notizen die Installation immer blockieren, bis Sie bestätigt
wurden oder den Anwender per E-Mail bleästigt haben.
Wählen Sie die Prioritäten der Fragen in Betreuerskripten sorgfältig. Einzelheiten über Prioritäten finden Sie unter debconf-devel(7). Die meisten Fragen sollten mittlere oder niedrige Prioritäten nutzen.
Die meisten Debian-Paketbetreuer haben nicht Englisch als Muttersprache. Daher ist es für sie nicht einfach, korrekt formulierte Schablonen zu verfassen.
Bitte benutzen (und missbrauchen) Sie die Mailingliste
<debian-l10n-english@lists.debian.org>. Lassen Sie Ihre Schablonen korrekturlesen.
Schlecht geschriebene Schablonen werfen ein armseliges Bild auf Ihr Paket, Ihre Arbeit ... oder sogar auf Debian selbst.
Vermeiden Sie soweit möglich technische Fachsprache. Wenn sich einige Begriffe für Sie vertraut anhören, könnten sie für andere unverständlich sein. Falls sie sich nicht vermeiden lassen, versuchen Sie sie zu erklären (benutzen Sie die längere Beschreibung). Versuchen Sie dabei, zwischen Aussagekraft und Einfachheit abzuwägen.
Debconf-Schablonen können übersetzt werden. Debconf bietet zusammen mit seinem Schwesterpaket po-debconf ein einfaches Gerüst, um Schablonen durch Übersetzer-Teams oder sogar einzelne Personen übersetzen zu lassen.
Bitte benutzen Sie Gettext-basierte Schablonen. Installieren Sie po-debconf auf Ihrem Entwicklungssystem und
lesen Sie dessen Dokumentation (man po-debconf ist ein
guter Anfang).
Vermeiden Sie, Schablonen häufig zu ändern. Das Ändern von Schablonen führt
zu Mehrarbeit für Übersetzer, deren Übersetzungen unvollständig werden. Eine
unvollständige Übersetzung ist eine Zeichenkette, bei der sich seit dem
Übersetzen das Original geändert hat und das daher eine Aktualisierung durch
den Übersetzer benötigt. Wenn die Änderungen klein genug sind, wird die
Originalübersetzung in den PO-Dateien beibehalten und mit
fuzzy gekennzeichnet.
Falls Sie planen, Änderungen an Ihren Originalschablonen vorzunehmen,
benutzen Sie bitte das Benachrichtigungssystem namens
podebconf-report-po, das vom Paket po-debconf bereitgestellt wird, um die
Übersetzer zu kontaktieren. Die meisten aktiven Übersetzer sind sehr
zugänglich und Ihre Arbeit zusammen mit Ihren geänderten Schablonen
einzubeziehen, wird Sie vor zusätzlichen Uploads bewahren. Falls Sie
Gettext-basierte Schablonen verwenden, werden die Namen und E-Mail-Adressen
der Übersetzer in den Kopfzeilen der PO-Dateien erwähnt und von
podebconf-report-po benutzt.
Ein empfohlene Art, das Hilfswerkzeug zu benutzen ist:
cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"
Dieser Befehl wird zuerst die PO- und POT-Dateien in
debian/po mit dem Schablonendateien synchronisieren,
die in debian/po/POTFILES.in aufgeführt sind. Dann wird
er einen Aufruf für neue Übersetzungen an die Mailingliste
<debian-i18n@lists.debian.org> senden. Am Schluss wird er außerdem einen Aufruf für
neue Übersetzungen an das Sprach-Team (im Feld
Language-Team jeder PO-Datei erwähnt) sowie den letzten
Übersetzer (erwähnt in Last-translator) senden.
Es wird immer gewürdigt, wenn Sie den Übersetzern einen Abgabetermin geben, so dass sie ihre Arbeit organisieren können. Bitte denken Sie daran, dass einige Übersetzer-Teams einen formalisierten Übersetzung-/Korrekturprozess haben und eine Zeitspanne, die kürzer als zehn Tage ist, als unangemessen angesehen wird. Eine kürzere Frist übt zuviel Druck auf die Übersetzer-Teams aus und sollte für sehr kleine Änderungen genommen werden.
Im Zweifelsfall können Sie auch das Übersetzer-Team für eine bestimmte
Sprache (debian-l10n-xxxxx@lists.debian.org) oder die Mailingliste
<debian-i18n@lists.debian.org> kontaktieren.
Wenn der Text einer Debconf-Schablone korrigiert wurde und Sie sicher sind, dass die Änderung keine Übersetzungen beeinflusst, seien Sie so nett zu Übersetzern, die Fuzzy-Markierungen aus deren Übersetzungen zu entfernen.
Falls Sie dies nicht tun, wird die ganze Schablone nicht übersetzt, bis Ihnen ein Übersetzer eine Aktualisierung zusendet.
Um die Fuzzy-Markierungen aus Übersetzungen zu
entfernen, können Sie msguntypot benutzen (Teil des
Pakets po4a).
Erzeugen Sie die POT- und PO-Dateien neu.
debconf-updatepo
Erstellen Sie eine Kopie der POT-Datei.
cp templates.pot templates.pot.orig
Erstellen Sie eine Kopie aller PO-Dateien.
mkdir po_fridge; cp *.po po_fridge
Ändern Sie die Debconf-Schablonen-Dateien, um den Tippfehler zu korrigieren.
Erzeugen Sie die POT- und PO-Dateien (wieder) neu.
debconf-updatepo
An dieser Stelle markiert die Korrektur des Tippfehlers alle Übersetzungen mit »fuzzy« und diese unglückliche Änderung ist die einzige zwischen den PO-Dateien Ihres Hauptverzeichnisses und den aus dem Kühlschrank. Hier nun eine Erklärung, wie das gelöst wird.
Verwerfen Sie die mit »fuzzy« markierte Übersetzung und stellen Sie die aus dem Kühlschrank wieder her.
cp po_fridge/*.po .
Führen Sie manuell die PO-Dateien mit der neuen POT-Datei zusammen, aber berücksichtigen Sie das nutzlose »fuzzy«.
msguntypot -o templates.pot.orig -n templates.pot *.po
Räumen Sie auf.
rm -rf templates.pot.orig po_fridge
Schablonentext sollte keinen Bezug auf Steuerelemente herstellen, die zu irgendwelchen Debconf-Schnittstellen gehören. Sätze wie If you answer Yes... haben keinen Sinn für Benutzer grafischer Oberflächen, die für die Beantwortung logischer Fragen Kontrollkästchen verwenden.
Zeichenkettenschablonen sollten außerdem vermeiden, Vorgabewerte in ihrer Beschreibung zu erwähnen. Erstens sind diese zusätzlich zu den Werten, die der Anwender sieht, vorhanden. Außerdem könnten sich diese Werte von der Auswahl des Paketbetreuers unterscheiden (zum Beispiel, wenn die Debconf-Datenbank vorbelegt war).
Versuchen Sie, allgemein ausgedrückt, Bezug auf Benutzeraktionen zu vermeiden. Geben Sie nur Tatsachen wieder.
Sie sollten vermeiden, in der ersten Person zu reden (I will do this... oder We recommend...). Der Rechner ist keine Person und die Debconf-Schablonen sprechen nicht stellvertretend für Debian-Entwickler. Sie sollten neutrale Formulierungen benutzen. Diejenigen unter Ihnen, die bereits wissenschaftliche Publikationen verfasst haben, können ihre Schablonen so schreiben, als würden Sie wissenschaftliche Papiere verfassen. Versuchen Sie jedoch, wenn möglich, eine aktive Anrede zu verwenden, wie Enable this if ... anstelle von This can be enabled if....
Dieser Teil stellt einige Informationen bereit, die meistens von der Handbuchseite debconf-devel(7) abgefragt wird.
resultiert in einem Eingabefeld freier Form, in das der Benutzer jegliche Zeichenkette eingeben kann.
gibt dem Benutzer eine Eingabeaufforderung für ein Passwort aus. Benutzen Sie dies mit Vorsicht. Vergegenwärtigen Sie sich, dass das Passwort, das der Benutzer eingibt, in die Debconf-Datenbank geschrieben wird. Sie sollten diesen Wert möglicherweise aus der Datenbank löschen, sobald dies möglich ist.
Eine Auswahl aus mehreren Werten. Die Auswahlmöglichkeiten müssen in einem
»Choices« benannten Feld angegeben werden. Trennen Sie die möglichen Werte
mit Komma und Leerzeichen, wie hier: Choices: yes, no,
maybe.
Falls Auswahlmöglichkeiten übersetzbare Zeichenketten sind, könnte das Feld
durch Benutzung von __Choices als übersetzbar
gekennzeichnet werden. Der doppelte Unterstrich wird jede Auswahl in eine
separate Zeichenkette heraustrennen.
Das System po-debconf bietet außerdem interessante Möglichkeiten nur einige Auswahlmöglichkeiten als übersetzbar zu kennzeichnen. Ein Beispiel:
Template: foo/bar Type: Select #flag:translate:3 __Choices: PAL, SECAM, Other _Description: TV standard: Please choose the TV standard used in your country.
In diesem Beispiel ist nur die Zeichenkette »Other« übersetzbar, während das andere Abkürzungen sind, die nicht übersetzt werden sollten. Obiges ermöglicht, dass nur »Other« in die POT- und PO-Dateien eingefügt wird.
Das Schaltersystem der Debconf-Schablonen bietet viele solcher Möglichkeiten. Die Handbuchseite po-debconf(7) führt all diese Möglichkeiten auf.
Wie der Datentyp »select«, außer dass der Benutzer eine beliebige Anzahl von Elementen aus der Auswahlliste auswählen kann (oder gar keins).
Statt per se eine Frage zu sein, gibt dieser Datentyp eine Anmerkung an, die dem Benutzer angezeigt werden kann. Sie sollte nur für wichtige Anmerkungen benutzt werden, die der Benutzer wirklich sehen sollte, weil Debconf großen Aufwand betreibt, um sicherzustellen, dass der Benutzer sie sieht und die Installation anhält, so dass der Benutzer eine Taste drückt und sogar in manchen Fällen eine Benachrichtigung per E-Mail bekommt.
Dieser Typ wurde entworfen, um Fehlermeldungen zu handhaben. Er ist meist dem Typ »note« ähnlich. Oberflächen könnten ihn unterschiedlich anzeigen (die Oberfläche von Cdebconf zeichnet beispielsweise einen roten statt des üblichen blauen Bildschirms).
Es wird empfohlen, diesen Typ für jegliche Nachricht zu verwenden, die die Aufmerksamkeit des Anwenders für irgendeine Art von Korrektur auf sich ziehen muss.
Schablonenbeschreibungen haben zwei Teile: kurz und länger. Die Kurzbeschreibung steht in der Zeile »Description:« der Schablone.
Die Kurzbeschreibung sollte knapp gehalten werden (ungefähr 50 Zeichen), so dass sie in den meisten Debconf-Schnittstellen untergebracht werden kann. Es hilft obendrein Übersetzern, wenn sie kurz gehalten wird, da Übersetzungen normalerweise dazu neigen, länger als das Original zu sein.
Die Kurzbeschreibung sollte für sich allein stehen können. Einige Schnittstellen zeigen standardmäßig die ausführliche Beschreibung nicht, nur dann, wenn der Benutzer danach fragt oder sogar überhaupt nicht an. Vermeiden Sie Dinge wie »Was möchten Sie tun?«
Die Kurzbeschreibung muss nicht notwendigerweise aus einem vollständigen Satz bestehen. Dies ist Teil der Forderung nach kurzen, brauchbaren Empfehlungen.
Die längere Beschreibung sollte die Kurzbeschreibung nicht Wort für Wort wiederholen. Falls Ihnen keine ausführliche Beschreibung einfällt, denken Sie zuerst etwas mehr nach. Schreiben Sie an Debian-devel. Bitten Sie um Hilfe. Nehmen Sie Schreibunterricht! Diese längere Beschreibung ist wichtig. Falls Sie nach allem noch immer nicht damit zurecht kommen, lassen Sie sie leer.
Die längere Beschreibung sollte in ganzen Sätzen verfasst sein. Absätze sollten kurz gehalten werden, um die Leserlichkeit zu verbessern. Vermischen Sie nicht zwei Ideen in einem Absatz, sondern benutzen Sie lieber einen anderen Absatz.
Seien Sie nicht zu gesprächig. Benutzer tendieren dazu, zu lange Bildflächen zu ignorieren. 20 Zeilen sind erfahrungsgemäß die Grenze, die Sie nicht überschreiten sollten, da dies bedeuted, dass Anwender klassische Dialogfenster nicht scrollen müssen und viele Leute tun das einfach nicht.
Die längere Beschreibung sollte keine Frage enthalten.
Um etwas über besondere Regeln zu erfahren, die vom Schablonentyp (string, boolean etc.) abhängen, lesen Sie das Folgende.
Dieses Feld sollte für »select«- und »multiselect«-Typen verwandt werden. Es enthält die Auswahlmöglichkeiten, die dem Benutzer angezeigt werden. Diese Auswahlmöglichkeiten sollten durch Kommas getrennt werden.
keine besondere Angabe, außer: Benutzen Sie den geeigneten Typ bezogen auf den vorhergehenden Abschnitt.
Es folgen spezifische Anweisungen für ordnungsgemäßes Verfassen der Beschreibung (kurz und länger), abhängig vom Schablonentyp.
Die Kurzbeschreibung ist eine Abfrage und kein Titel. Vermeiden Sie den Fragestil (IP address?) und geben Sie offenen Abfragen (IP address:) den Vorzug. Es wird empfohlen Doppelpunkte zu benutzen.
Die längere Beschreibung ist eine Ergänzung der Kurzbeschreibung. Im erweiterten Teil erklären Sie, was gefragt ist, anstatt die gleiche Frage in längerer Formulierung wieder zu stellen. Benutzen Sie ganze Sätze. Von knappem Schreibstil wird strikt abgeraten.
Die Kurzbeschreibung sollte in der Frageform ausgedrückt werden, die kurz gehalten und generell mit einem Fragezeichen beendet werden sollte. Knapper Schreibstil ist erlaubt und sogar gewollt, falls die Frage eher lang ist. (Denken Sie daran, dass Übersetzungen oft länger als die Originalversionen sind.)
Nochmals: Bitte vermeiden Sie, sich auf Schnittstellen-spezifische Dinge zu beziehen. Es ist ein häufiges Missverständnis bei solchen Schablonen, wenn Sie Ja-Typ-Konstruktionen antworten.
Die Kurzbeschreibung ist eine Abfrage und kein Titel. Benutzen Sie keine nutzlosen »Please choose...«-Konstruktionen. Anwender sind klug genug herauszufinden, dass sie etwas auswählen sollen ... :)
Die längere Beschreibung wird die Kurzbeschreibung vervollständigen. Sie könnte sich auf die verfügbaren Auswahlmöglichkeiten beziehen. Sie könnte zudem erwähnen, dass der Anwender unter mehr als einer verfügbaren Auswahlmöglichkeit wählen kann, falls es sich um eine »multiselect«-Schablone handelt.
Die Kurzbeschreigung sollte als Titel betrachtet werden.
Die längere Beschreibung ist das, was als detaillierte Erklärung der Notiz angezeigt wird. Sätze, kein knapper Schreibstil.
Missbrauchen Sie Debconf nicht. Notizen
sind die häufigste Art, auf die Debconf missbraucht wird. Wie steht doch in
der Handbuchseite von »debconf-devel« geschrieben: Es ist am Besten, dies
nur für Warnungen über sehr ernsthafte Probleme zu benutzen. Die Dateien
NEWS.Debian oder README.Debian
sind für viele Notizen der passende Ort. Denken Sie, wenn Sie dies lesen,
darüber nach, Ihre Schablonen des Typs »notes« zu Einträgen in
NEWS.Debian oder README.Debian
umzuwandeln und existierende Übersetzungen für die Zukunft aufzubewahren.
Falls sich »Choices« zu oft ändert, sollten Sie in Betracht ziehen, zum __Choices-Trick zu greifen. Dies wird jede einzelne Auswahl in eine einzelne Zeichenkette aufteilen, was Übersetzern beträchtlich bei ihrer Arbeit helfen wird.
Falls der Vorgabewert für eine Auswahlschablone sich wahrscheinlich abhängig von der Sprache des Anwenders unterscheidet (zum Beispiel, weil es sich bei der Auswahl um eine Sprachauswahl handelt), benutzen Sie bitte den _Default-Trick.
Dieses Spezialfeld ermöglicht Übersetzern, die am Besten zu ihrer Sprache passende Auswahl zu nehmen. Es wird die vorgegebene Auswahl sein, wenn ihre Sprache benutzt wird, während Ihre eigene erwähnte »Default Choice« benutzt wird, wenn Sie Englisch benutzen.
Ein Beispiel aus den Schablonen des Pakets Geneweb:
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 # instead of the default. # WARNING : you MUST use the ENGLISH NAME of your language # For instance, the french translator will need to put French (fr) here. _Default: English[ translators, please see comment in PO files] _Description: Geneweb default language:
Beachten Sie, dass die Benutzung von Klammern Kommentare in Debconf-Feldern erlaubt. Beachten Sie außerdem, dass die Benutzung von Kommentaren in Dateien zu sehen sein wird, mit denen Übersetzer arbeiten.
Die Kommentare werden benötigt, da der _Default-Trick etwas verwirrendes ist: Die Übersetzer könnten ihre eigene Auswahl nehmen.
Benutzen Sie KEIN leeres »Default«-Feld. Falls Sie keine Vorgabewerte benutzen möchten, benutzen Sie Default überhaupt nicht.
Falls Sie Po-debconf benutzen (und das sollten Sie, lesen Sie Abschnitt 6.5.2.2, „Seien sie nett zu Übersetzern“), erwägen Sie, dieses Feld übersetzbar zu machen, wenn Sie der Meinung sind, es könnte übersetzt werden.
Falls der Vorgabewert von Sprache oder Land abhängen könnte (zum Beispiel, weil es sich bei der Auswahl um eine Sprachauswahl handelt), ziehen Sie in Betracht, den Typ _Default zu benutzen, der in po-debconf(7) dokumentiert wird.
Der zweite Abschnitt enthält globale Informationen für Entwickler, um Übersetzern das Leben leichter zu machen. Weitere Informationen für Übersetzer und Entwickler, die sich für Internationalisierung interessieren, sind in der Dokumentation Internationalisierung und Lokalisierung verfügbar.
Wie Portierende haben auch Übersetzer noch andere Aufgaben. Sie arbeiten an vielen Paketen und müssen mit vielen verschiedenen Paketbetreuern zusammenwirken. Außerdem ist Englisch meist nicht ihre Muttersprache. Sie sollten ihnen daher besondere Geduld entgegenbringen.
Das Ziel von debconf war die
Vereinfachung der Paketkonfiguration für Betreuer und Anwender. Ursprünglich
wurde die Übersetzung von Debconf-Schablonen mit
debconf-mergetemplate gehandhabt. Nun wird diese Technik
jedoch missbilligt. Die Internationalisierung von debconf ist am besten mit dem Paket po-debconf zu erreichen. Diese Methode ist
sowohl für Betreuer als auch für Übersetzer einfacher. Es werden
Umwandlungsskripte bereitgestellt.
Wenn po-debconf benutzt wird, werden
sie Übersetzungen in .po-Dateien gespeichert (mit
gettext-Übersetzungstechniken herausgezogen). Spezielle
Schablonendateien enthalten die Originalnachrichten und markieren, welche
Felder übersetzbar sind. Wenn Sie den Wert eines übersetzbaren Feldes durch
Aufruf von debconf-updatepo ändern, wird die Übersetzung
für Übersetzer als aufmerksamkeitsbedürfend gekennzeichnet. Dann, zur
Build-Zeit, wird das Programm dh_installdebconf wie von
Zauberhand dafür sorgen, dass alle Schablonen zusammen mit den aktuellen
Übersetzungen in die Binärpakete einfließen. Weitere Einzelheiten können Sie
der Handbuchseite po-debconf(7) entnehmen.
Internationalisierte Dokumentation für Anwender ist wichtig, bereitet aber viel Mühe. Es gibt keine Möglichkeit, all diese Arbeit zu beseitigen, aber Sie können den Übersetzern einige Dinge erleichtern.
Falls Sie Dokumentationen in irgendwelchem Umfang betreuen, ist es für
Übersetzer einfacher, wenn Sie Zugriff auf das Versionsverwaltungssystem
haben. Dadurch können Übersetzer die Unterschiede zwischen zwei Versionen
der Dokumentation anschauen, so dass sie beispielsweise sehen können, was
neu übersetzt werden muss. Es wird empfohlen, dass die übersetzte
Dokumentation eine Notiz darüber bereithält, auf welcher Revision der
Quellenverwaltung die Übersetzung basiert. Ein interessantes System wird von
doc-check aus dem debian-installer-Paket bereitgestellt, das eine
Übersicht über den Übersetzungsstatus für eine angegebene Sprache
anzeigt. Dazu werden strukturierte Kommentare für die aktuelle Revision der
zu übersetzenden Datei und für eine übersetzte Datei die Revision des
Originals auf der die Übersetzung basiert, angezeigt. Möglicherweise möchten
Sie dies anpassen und in Ihrem VCS-Bereich bereitstellen.
Falls Sie XML- oder SGML-Dokumentationen betreuen, wird geraten, dass Sie jegliche sprachabhängigen Informationen isolieren und diese als Instanzen in einer separaten Datei definieren, die in allen verschiedenen Übersetzungen enthalten ist. Dies macht es beispielsweise viel einfacher, URLs über mehrere Dateien hinweg aktuell zu halten.
Einige Werkzeuge (z.B. po4a,
poxml oder translate-toolkit) sind darauf spezialisiert,
übersetzbares Material aus verschiedenen Formaten zu extrahieren. Sie
erstellen PO-Dateien, ein für Übersetzer ziemlich häufiges Format, das eine
Übersicht darüber gibt, was übersetzt werden muss, wenn das übersetzte
Dokument aktualisiert wurde.
Die Dateien config.sub und
config.guess von autoconf aktuell zu
halten ist für Portierende kritisch, insbesondere auf eher unbeständigen
Architekturen. Einige sehr gute Paketierungsvorgehensweisen für irgendwelche
Pakete, die autoconf und/oder automake
benutzen, wurden in /usr/share/doc/autotools-dev/README.Debian.gz aus dem Paket autotools-dev zusammengefasst. Es wird
eindringlich geraten, diese Datei und die folgenden Empfehlungen zu lesen.
Bibliotheken unterscheiden sich immer von Paketen aus unterschiedlichen Gründen. Die Richtlinien verhängen mehrere Beschränkungen, um ihre Verwaltung zu erleichtern und sicherzustellen, dass Upgrades so einfach wie möglich sind, wenn eine neue Originalversion herauskommt. Eine kaputte Bibliothek kann dazu führen, dass Dutzende davon abhängige Pakete kaputtgehen.
Gute Vorgehensweisen für das Paketieren von Bibliotheken wurden in der Anleitung zum Paketieren von Bibliotheken zusammengefasst.
Achten Sie darauf, dass Sie den Richtlinien für Dokumentation folgen.
Falls Ihr Paket Dokumentation enthält, die aus XML oder SGML erstellt wurde, wird empfohlen, nicht die XML- oder SGML-Quellen im (in den) Binärpaket(en) mitzuliefern. Falls Anwender die Quelle der Dokumentation möchten, sollten sie die Paketquelle abrufen.
Die Richtlinie gibt an, dass die Dokumentation im HTML-Format weitergegeben werden sollte. Außerdem wird empfohlen, die Dokumentation im PDF-Format und als Klartext mitzuliefern, falls geeignet und falls die Ausgabe in einer vernünftigen Qualität möglich ist. Es ist allgemein jedoch nicht angemessen, Klartextversionen von Dokumentationen mitzuliefern, deren Quellformat HTML ist.
Bedeutende mitgelieferte Handbücher sollten sich selbst bei der Installation
mit doc-base registrieren. Weitere
Einzelheiten erhalten Sie in der Dokumentation des Pakets doc-base.
Die Debian-Richtlinien (Abschnitt 12.1) schreiben vor, dass Handbuchseiten jedes Programm, jedes Hilfswerkzeug und jede Funktion begleiten sollten und für andere Objekte, wie Konfigurationsdateien, nahegelegt werden. Falls die von Ihnen paketierte Arbeit nicht über eine solche Handbuchseite verfügt, dann überlegen Sie sich, eine zu schreiben, die Ihrem Paket beigefügt und an die Originalautoren gesandt wird.
Die Handbuchseiten müssen nicht direkt im Troff-Format geschrieben werden. Beliebte Quellformate sind Docbook, POD und reST, die mit xsltproc, pod2man beziehungsweise rst2man umgewandelt werden können. In geringerem Maße kann außerdem das Programm help2man benutzt werden, um einen Abschnitt zu schreiben.
Mehrere besondere Typen von Paketen haben spezielle Unterrichtlinien und zugehörige Paketierungsregeln und -Vorgehensweisen:
Perl zugehörige Pakete haben eine Perl-Richtlinie. Einige Beispiele für
Pakete, die dieser Richtlinie folgen, sind libdbd-pg-perl (binäres Perl-Modul) oder
libmldbm-perl
(architekturunabhängiges Perl-Modul).
Python zugehörige Pakete haben ihre Python-Richtlinie. Siehe
/usr/share/doc/python/python-policy.txt.gz im Paket python.
Emacs zugehörige Pakete haben die Emacs-Richtlinie.
Java zugehörige Pakete haben ihre Java-Richtlinie.
Ocaml zugehörige Pakete haben ihre eigene Richtlinie, die unter
/usr/share/doc/ocaml/ocaml_packaging_policy.gz im Paket ocaml
gefunden werden kann. Ein gutes Beispiel ist das Quellpaket camlzip.
Pakete, die XML- oder SGML-DTDs bereitstellen, sollten konform zu den
Empfehlungen in Paket sgml-base-doc
sein.
Lisp-Pakete sollten sich selbst mit common-lisp-controller registrieren. Siehe dazu
/usr/share/doc/common-lisp-controller/README.packaging.
Es ist nicht unüblich, eine größere Menge architekturunabhängiger Daten mit einem Programm zu paketieren, Zum Beispiel Audiodateien, eine Symbolsammlung, Hintergrundmuster oder grafische Dateien. Falls die Größe dieser Daten vernachlässigbar im Vergleich zum Rest des Pakets ist, ist es wahrscheinlich am besten, alles in einem einzelnen Paket zu halten.
Ist die Größe allerdings beachtlich, denken Sie darüber nach, sie in ein
separates architekturunabhängiges Paket (_all.deb)
auszulagern. Imdem Sie dies tun, vermeiden Sie nutzlose Vervielfältigung der
gleichen Daten in elf oder mehr .debs, eins je Architektur. Indem dies
einigen zusätzlichen Zuschlag zu den Packages-Dateien
hinzufügt, spart es viel Plattenplatz auf Debian-Spiegeln. Das Heraustrennen
architekturunabhängiger Daten vermindert auch die Ausführungszeit von
lintian (siehe Abschnitt A.2, „Lint-Werkzeuge für Pakete“), wenn es für
das ganze Debian-Archiv ausgeführt wird.
Falls Sie eine bestimmte Locale während des Builds benötigen, können Sie mittels dieses Tricks eine temporäre Datei erstellen:
Falls Sie LOCPATH auf die Entsprechung von
/usr/lib/locale und LC_ALL auf den
Namen der Locale setzen, die sie generieren, sollten Sie erreichen, was Sie
möchten ohne dass Sie Root sind. Etwas wie Folgendes:
LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 mkdir -p $LOCALE_PATH localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET # Using the locale LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
Deborphan ist ein Programm, das Anwendern hilft Pakete aufzuspüren, die sicher vom System entfernt werden können, d.h. diejenigen, von denen keine Pakete abhängen. Die Standardoperation ist, nur innerhalb der Abschnitte »libs« und »oldlibs« zu suchen, um Jagd auf unbenutzte Bibliotheken zu machen. Wenn aber das richtige Argument übergeben wird, versucht es auch andere nutzlose Pakete zu erwischen.
Mit --guess-dummy versucht deborphan
zum Beispiel alle vorübergehenden Pakete zu suchen, die zum Upgrade benötigt
wurden, die nun aber sicher entfernt werden können. Dazu sucht es nach den
Zeichenketten »dummy« oder »transitional« in dessen Kurzbeschreibung.
Wenn Sie also solch ein Paket erstellen, achten Sie bitte darauf, diesen Text zu Ihrer Kurzbeschreibung hinzuzufügen. Falls Sie sich nach Beispielen umsehen, führen Sie einfach apt-cache search .|grep dummy oder apt-cache search .|grep transitional aus.
Außerdem wird empfohlen, den Abschnitt in oldlibs und die
Priorität in extra anzupassen, um die Arbeit von
deborphan zu erleichtern.
Es gibt zwei Arten von Original-Quell-Tarballs: unberührte Quellen und neu paketierte Quellen der Originalautoren.
Das charakteristische Merkmal eines unberührten Tarballs ist, dass die
.orig.tar.{gz,bz2,xz}-Datei Byte für Byte identisch mit
einem offiziell weitergegebenen Tarball des Originalautors ist.[5] Dies ermöglicht die Benutzung von Prüfsummen, um
auf einfache Weise alle Änderungen zwischen Debians Version und der der
Originalautoren zu prüfen, die in der Diff-Datei in Debian enthalten
sind. Falls außerdem die Originalquelle riesig ist, können Originalautoren
und andere, die bereits den Original-Tarball haben, Download-Zeit sparen,
falls sie Ihre Paketierung im Detail inspizieren möchten.
Es gibt keine allgemein anerkannten Richtlinien, denen Originalautoren betreffend der Verzeichnisstruktur innerhalb ihres Tarballs folgen, aber dpkg-source ist dennoch in der Lage mit den meisten Tarballs von Originalautoren als unberührte Quelle umzugehen. Seine Strategie entspricht dem Folgenden:
Es entpackt den Tarball in eine leeres temporäres Verzeichnis mittels
zcat path/to/Paketname_Originalversion.orig.tar.gz | tar xf -
Falls das temporäre Verzeichnis danach nur ein Verzeichnis und keine anderen
Dateien enthält, benennt dpkg-source dieses Verzeichnis
in
Paketname_Originalversion(.orig)
Andernfalls muss der Tarball der Originalautoren ohne ein sonst übliches
Verzeichnis der obersten Ebene gepackt worden sein (Schande über den
Originalautor!). In diesem Fall benennt dpkg-source das
temporäre Verzeichnis selbst in
Paketname_Originalversion(.orig)
Sie sollten Pakete, wenn möglich, mit einem unberührten Quell-Tarball hochladen, aber es gibt viele Gründe, warum das manchmal nicht möglich ist. Dies ist der Fall, wenn die Originalautoren die Quelle gar nicht als Gzip-gepackte Tar-Datei weitergeben oder falls der Tarball der Originalautoren nicht DFSG-freies Material enthält, das Sie vor den Hochladen entfernen müssen.
In diesen Fällen muss der Entwickler selbst eine geeignete
.orig.tar.{gz,bz2,xz}-Datei bauen. Solch ein Tarball
wird neu paketierten Originalquellen zugeordnet. Beachten Sie, dass sich
eine neu paketierte Originalquelle von einem nativen Debian-Paket
unterscheidet. Eine neu paketierte Quelle kommt mit Debian-spezifischen
Änderungen in einem separaten .diff.gz oder
.debian.tar.{gz,bz2,xz} daher und hat eine
Versionsnummer, die sich aus der Originalversion
und der Debian-version zusammensetzt.
Es könnte Gründe geben, aus denen es wünschenswert wäre, die Quelle neu zu
paketieren, obwohl die Originalautoren ein
.tar.{gz,bz2,xz} verteilen, dass im Prinzip in seiner
unberührten Form benutzt werden könnte. Der naheliegendste Grund ist, wenn
signifikante Platzersparnis durch Neukomprimierung des
Tar-Archivs oder Entfernen von wirklich nutzlosem Müll aus dem
Qriginalarchiv erzielt werden kann. Handeln Sie hier nach eigenem Ermessen,
aber seien Sie darauf vorbereitet, Ihre Entscheidung zu verteidigen, falls
Sie eine Quelle neu paketieren, die unberührt sein könnte.
Ein neu paketiertes .orig.tar.{gz,bz2,xz}
sollte im resultierenden Quellpaket
dokumentiert sein. Detaillierte Informationen, wie die neu paketierte Quelle
gewonnen wurde und wie dies reproduziert werden kann, sollten in
debian/copyright bereitgestellt werden. Es ist außerdem
eine gute Idee, ein get-orig-source-Target in Ihrer
debian/rules-Datei bereitzustellen, die den Prozess
wiederholt, wie im Richtlinien-Handbuch beschrieben Main building script:
debian/rules.
sollte keine Datei enthalten, die nicht von dem/den Origianlautor(en) stammt oder deren Inhalt von Ihnen geändert wurde.[6]
sollte außer, wenn es aus rechtlichen
Gründen unmöglich ist, die ganze Erstellungs- und Portierungsinfrastruktur
aufbewahren, die vom Originalautor bereitgestellt wurde. Es ist zum Beispiel
kein ausreichender Grund für das Weglassen einer Datei, wenn sie nur für die
Erstellung unter MS-DOS benutzt wird. Gleichermaßen sollte ein
Makefile, das vom Originalautor bereitgestellt wurde
nicht einmal dann weggelassen werden, wenn das erste, was Ihre
debian/rules tut, das Überschreiben durch Ausführen
eines Konfigurationsskripts ist.
(Begründung: Es ist üblich für Debian-Anwender, die Software für nicht-Debian-Plattformen erstellen möchten, die Quellen von einem Debian-Spiegel abzurufen, anstatt den Punkt der ordnungsgemäßen Originaldistribution zu suchen).
sollte als Namen des Verzeichnisses auf
der obersten Ebene des Tarballs
Paketname-Originalversion.orig
sollte mit Gzip oder Bzip mit der maximalen Komprimierung gepackt werden.
Manchmal ist es nötig, binäre Dateien zu ändern, die im Original-Tarball
enthalten sind oder binäre Dateien hinzuzufügen, die nicht darin enthalten
sind. Dies wird vollständig unterstützt, wenn Sie Quellpakete im Format »3.0
(quilt)« benutzen. Lesen Sie die Handbuchseite
dpkg-source(1),
um weitere Einzelheiten zu erfahren. Wenn Sie das ältere Format »1.0«
benutzen, können binäre Dateien nicht im .diff.gz
gespeichert werden, daher müssen Sie eine mit uuencode
(oder ähnlichem) kodierte Version der Datei(en) speichern und zur
Erstellungszeit in debian/rules entschlüsseln (und an
ihren offiziellen Platz verschieben).
Ein Debug-Paket ist ein Paket, dessen Name mit -dbg endet. Es enthält zusätzliche Informationen, die gdb benutzen kann. Da Debian-Programme standardmäßig unverhüllt sind, sind Debugging-Informationen, einschließlich Namen und Zeilennummern andernfalls nicht verfügbar, wenn gdb auf Debian-Programmen ausgeführt wird. Debug-Pakete ermöglichen Anwendern, die diese zusätzlichen Debugging-Informationen benötigen, sie zu installieren ohne das normale System mit diesen Informationen aufzublähen.
Es liegt beim Paketbetreuer, ob ein Debug-Paket erstellt wird oder nicht. Betreuer werden aufgefordert Debug-Pakete für Bibliothekenpakete zu erstellen, da dies bei der Fehlersuche in vielen Programmen helfen kann, die mit der Bibliothek verlinkt werden. Im Allgemeinen gibt es keine Notwendigkeit für Debug-Pakete zu allen Programmen; dies würde das Archiv aufblähen. Falls aber ein Betreuer findet, dass Anwender oft die Debugging-Version eines Programms benötigen, kann es lohnenswert sein, ein Debug-Paket dafür zu erstellen. Programme die zur Kerninfrastruktur gehören, wie Apache oder der X-Server sind ebenfalls geeignete Kandidaten für Debug-Pakete.
Einige Debug-Pakete könnten ein ganz spezielles Debugging-Build einer
Bibliothek oder eines anderen Programms haben, aber die meisten können
Speicher und Build-Zeit sparen, indem sie stattdessen separate
Debugging-Symbole enthalten, die gdb spontan finden und
laden kann, wenn in einem Programm oder einer Bibliothek nach Fehlern
gesucht wird. Die Konvention in Debian besagt, dass diese Symbole in
/usr/lib/debug/
aufbewahrt werden, wobei PfadPfad der Pfad zum
ausführbaren Programm oder der Bibliothek ist. Debugging-Symbole für
/usr/bin/foo wandern beispielsweise nach
/usr/lib/debug/usr/bin/foo und Debugging-Symbole für
/usr/lib/libfoo.so.1 nach
/usr/lib/debug/usr/lib/libfoo.so.1.
Die Debugging-Symbole können mit objcopy --only-keep-debug aus einer Objektdatei extrahiert werden. Dann kann die Objektdatei enthüllt und objcopy --add-gnu-debuglink benutzt werden, um den Pfad zur Debugging-Symboldatei anzugeben. objcopy(1) erklärt im Detail, wie dies funktioniert.
Der Befehl dh_strip in debhelper unterstützt das Erstellen von
Debug-Paketen und kann sich um die Benutzung von objcopy
kümmern, um die Debugging-Symbole für Sie herauszusuchen. Falls Ihr Paket
debhelper benutzt, müssen Sie nur
dh_strip --dbg-package=libfoo-dbg aufrufen und einen
Eintrag in debian/control für das Debug-Paket
hinzufügen.
Beachten Sie, dass Debug-Pakete von dem Paket abhängen sollten, für das sie Debugging-Symbole bereitstellen und diese Abhängigkeit sollte mit einer Version versehen werden. Zum Beispiel:
Depends: libfoo (= ${binary:Version})
Ein Meta-Paket ist meist ein leeres Paket, das es vereinfacht, eine
Zusammenstellung von Paketen zu installieren, die sich im Lauf der Zeit
weiterentwickeln können. Es erreicht dies, indem es von allen Paketen der
Zusammenstellung abhängt. Dank der Fähigkeiten von APT kann der Betreuer des
Meta-Pakets die Abhängigkeiten anpassen und das System des Anwenders wird
automatisch die zusätzlichen Pakete erhalten. Die weggelassenen Pakete, die
automatisch installiert wurden, werden außerdem als Kandidaten für das
Entfernen gekennzeichnet (und werden sogar durch aptitude
automatisch entfernt). gnome und
linux-image-amd64 sind zwei
Beispiele für Meta-Pakete (gebaut durch die Quellpakete meta-gnome2 und linux-latest).
Die ausführliche Beschreibung des Meta-Pakets muss ihren Zweck klar dokumentieren, so dass die Benutzer wissen, was sie verlieren, wenn sie das Paket entfernen. Es wird empfohlen, genau über die Konsequenzen zu informieren. Dies ist besonders für Meta-Pakete wichtig, die während der anfänglichen Installation installiert werden und nicht explizit durch den Benutzer installiert wurden. Diese neigen dazu, wichtig für reibungslose Upgrades des Systems zu sein und der Benutzer sollte entmutigt werden, sie zu entfernen, um mögliche Schäden zu vermeiden.
[5] Originalautoren können nicht daran gehindert werden, den von ihnen
verteilten Tarball zu ändern, ohne die Versionsnummer zu erhöhen. Daher kann
nicht gewährleistet werden, dass ein unberührter Tarball mit dem identisch
ist, was die Originalautoren aktuell zu irgendeinem
Zeitpunkt weitergeben. Alles was erwartet werden kann, ist, dass es
identisch mit etwas ist, das die Originalautoren einmal weitergegeben
haben. Falls sich später ein Unterschied ergibt (etwa,
wenn die Originalautoren merken, dass sie in ihrer Verteilung des Originals
keine maximale Komprimierung nutzen und es dann erneut mit
gzip packen), ist das einfach Pech. Da es keine
brauchbare Möglichkeit gibt, ein neues
.orig.tar.{gz,bz2,xz} für die gleiche Version
hochzuladen, gibt es auch keinen Punkt, an dem diese Situation als ein
Fehler behandelt wird.
[6] Als besondere Ausnahme könnte, falls das Auslassen unfreier Dateien dazu
führen würde, dass das Build der Quelle ohne Unterstützung aus dem
Debian-Diff fehlschlägt, das Bearbeiten der Dateien anstelle des Weglassens
unfreier Teile davon und/oder Erklären der Situation in einer
README.source-Datei im Wurzelverzeichnis der Quelle
angemessen sein. Ermahnen Sie in diesem Fall aber auch den Originalautor,
unfreie Komponenten leichter aus dem Quelltext heraustrennbar zu machen.