FreeBSD Documentation Project: Beiträge einreichen
Ich habe eine neue Anleitung geschrieben. Wie kann ich diese einreichen?
Danke, dass Sie unsere Dokumentation erweitern wollen.
Sie müssen Ihre Dokumentation dem Documentation Project zur Verfügung stellen, damit Ihr Beitrag geprüft werden kann. Dazu hinterlegen Sie das Dokument beispielsweise auf einem FTP- oder Webserver.
Danach schicken Sie eine E-Mail an die Mailingliste
FreeBSD-doc
, in der Sie Ihren Beitrag kurz beschreiben
und vor allem mitteilen, wo Sie ihn hinterlegt habt. Außerdem
sollten Sie die Mitglieder des FreeBSD Documentation Projects um
die Prüfung Ihres Beitrags bitten.
Ist es Ihnen nicht möglich, Ihren Beitrag auf einem Server zu
hinterlegen, können Sie ihn auch direkt an die Mailingliste
FreeBSD-doc
schicken. Denken Sie aber daran, dass Ihre
E-Mail in diesem Fall nur "normalen" Text enthalten darf.
Falls Ihr Beitrag auch für andere Mailinglisten interessant ist,
sollte Sie Ihre E-Mail als Kopie auch an andere Mailinglisten
schicken und um Kommentare bitten. Handelt es sich bei Ihrem
Beitrag etwa um eine Anleitung zur Aktualisierung des Quellcodes
mit CVSup, so ist dies auch für die Leser der Mailinglisten
FreeBSD-current
und FreeBSD-stable
interessant.
Nachdem Ihr Beitrag geprüft wurde und Sie eventuelle Verbesserungsvorschläge in Ihr Dokument aufgenommen haben, können Sie Ihren Beitrag einreichen.
Dazu verpacken Sie Ihr Dokument in ein tar-Archiv. Besteht Ihr
Dokument beispielsweise aus den drei Dateien eins
,
zwei
, und drei
, die alle in das
gemeinsame tar-Archiv doc.tar
aufgenommen werden
sollen, verwenden Sie folgenden Befehl:
% tar cf doc.tar eins zwei drei
Danach komprimieren Sie das tar-Archiv:
% gzip -9 doc.tar
Als Ergebnis erhalten Sie die komprimierte Datei
doc.tar.gz
.
Als letzten Schritt der Vorbereitung kodieren Sie diese Datei noch, damit sie von allen E-Mail-Programmen korrekt erkannt und verarbeitet wird:
% uuencode doc.tar.gz doc.tar.gz > doc.uue
Nun können Sie das FreeBSD Documentation Project über Ihren Beitrag informieren. Der korrekte Weg dafür ist der Einsatz von send-pr, das auf Ihrem System bereits installiert sein sollte. Alternativ können Sie auch das Internetformular zum Einreichen von Problemberichten verwenden.
Nur so kann sichergestellt werden, dass Ihr Beitrag auch korrekt erfasst wird. Wenn Sie einen Problembericht (PR) einreichen, erhält dieser eine eindeutige Nummer. Ein Committer wird diesen PR übernehmen und Ihrem Beitrag weiterbearbeiten. Weitere Informationen zu diesem Thema finden Sie im Artikel Writing FreeBSD Problem Reports.
Die Bedienung von send-pr ist relativ einfach. Die Aufgabe des Programms ist es, eine speziell formatierte E-Mail an eine bestimmte E-Mail-Adresse zu schicken. Wenn Sie send-pr aufrufen, wird automatisch Ihr Standardeditor (beispielsweise vi oder emacs) mit einer von Ihnen auszufüllenden Vorlage geladen, die auch einige zusätzliche Anweisungen enthält.
Achten Sie beim Ausfüllen des Formulars darauf, dass Sie im Feld
"Category" den Wert "docs" eintragen und dass im Feld Class" der
Eintrag "change-request" steht. Im "Body"-Bereich fügen Sie die
vorhin erstellte .uue
-Datei ein.
Wenn Sie den Editor beenden, wird der PR als E-Mail an die korrekte Adresse geschickt. Kurz darauf erhalten Sie (wiederum als E-Mail) eine Bestätigung, die insbesondere die Ihrem PR zugewiesene eindeutige Nummer enthält. Diese PR-Nummer können Sie dazu verwenden, den aktuellen Status Ihres Beitrags zu prüfen.
Ich habe ein bereits vorhandenes Dokument verbessert. Wie kann ich meine Korrekturen einreichen?
Danke, dass Sie unsere Dokumentation verbessern wollen.
In diesem Fall müssen Sie eine spezielle Datei, eine sogenannte Differenz (diff) erstellen. Diese Differenz enthält alle von Ihnen durchgeführten Änderungen. Dadurch wird es den Committern erleichtert, Ihre Änderungen zu finden und zu prüfen. Sie haben den Vorteil, dass Sie nicht umständlich erklären müssen, was Sie geändert haben. Nichtsdestotrotz sollten Sie natürlich begründen können, warum Sie diese Änderung für nötig halten.
Um eine Differenz (einen "Diff") zu erstellen, gehen Sie wie folgt vor:
-
Erstellen Sie eine Kopie der zu ändernden Datei (in diesem Fall
foo.xml
): do% cp foo.xml foo.xml.old
-
Nun führen Sie Ihre Änderungen in foo.xml durch.
% vi foo.xml ... tipp tipp tipp ... ... Änderungen testen, Tippfehler suchen und korrigieren ...
-
Danach erzeugen Sie die Differenz:
% diff -u foo.xml.old foo.xml > foo.diff
Mit diesem Befehl werden die beiden Dateien verglichen und die Unterschiede in die Datei
foo.diff
geschrieben.
Als letzten Schritt senden Sie die erstellte Differenz
foo.diff
an das Documentation Project. Dazu erstellen
Sie wiederum einen PR. Im Unterschied zur Erstellung einer neuen
Anleitung, enthält der "Body"-Bereich nun aber die von Ihnen
erstellte Differenz foo.diff
.