FreeBSD The Power to Serve

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:

  1. Erstellen Sie eine Kopie der zu ändernden Datei (in diesem Fall foo.xml): do

        % cp foo.xml foo.xml.old
  2. Nun führen Sie Ihre Änderungen in foo.xml durch.

        % vi foo.xml
        ... tipp tipp tipp ...
    
        ... Änderungen testen, Tippfehler suchen und korrigieren ...
  3. 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.


Last modified on: 19. Juni 2021 by Danilo G. Baio