PostgreSQL Dokumentation noch besser machen

Bei unseren Arbeiten zum Thema “PostgreSQL für Delfine und Seelöwen” habe ich die PostgreSQL Dokumentation zum Thema Replikation durchgeackert.

Da ich bei diesem Thema noch nicht ganz so fit bin, schaue ich bei einigen Stichworten (Parametern, Funktionen, etc.) immer mal wieder gerne nach, was diese genau bedeuten oder wie sie genau funktionieren (RTFM!). Genau dafür wurden ja ursprünglich mal die Links erfunden, welche zuerst Gopher und später das Internet/WWW (http) so populär gemacht haben.

Leider fehlen aber in besagter Dokumentation oft diese Links, was den Lesefluss behindert.

Zum Glück aber ist PostgreSQL ein Open Source Projekt und Mitarbeit soll ja hochwillkommen sein! Also könnte ich ja, statt nur dumm über die Dokumentation rumzumosern, die entsprechenden fehlenden Links selber hinzufügen. Aber wie geht das denn genau in einem für mich neuen und daher noch etwas ungewohnten Ökosystem? Dabei hat mir ein Artikel von Elizabeth Christensen von Crunchy Data mit dem Titel: Contributing to Postgres 101: A Beginner’s Experience beim Einstieg geholfen.

Da ich selber Null Ahnung vom Programmieren habe, sehe ich beim Dokumentation Verbessern eine gute Möglichkeit, mich aktiv ins Projekt einzubringen und mitzuhelfen…

PostgreSQL Dokumentation verbessern

Die PostgreSQL Dokumentation liegt direkt im Server-Repository. Also ziehen wir uns als erstes mal das Git-Repository vom PostgreSQL Server runter:

$ git clone http://git.postgresql.org/git/postgresql.git

Die nächste Herausforderung besteht darin, die richtige Datei zu finden:

$ cd postgresql/doc/src/sgml

Hierbei hilft mit der grep Befehl in all seinen Spielarten weiter:

$ grep -r 'Planning for High Availability' *.sgml
high-availability.sgml:    <title>Planning for High Availability</title>

Das richtige Dokument scheint high-availability.sgml zu sein. Die PostgreSQL Dokumentation selbst ist in SGML verfasst, welche ähnlich wie HTML und nicht sonderlich schwer zu erlernen ist.

Diese SGML-Dateien lassen sich gut mit dem Editor der Wahl und entsprechendem Code-Highlighting lesen und ändern.

Dann geht es daran, die einzelnen Stichworte zu überprüfen, ob sie schon korrekt mit Markups versehen sind und wenn ja, diese mit Links zu versehen:

Achtung: Hierbei ist zu beachten, dass die Stichworte mit “_” (Unterstrich) und die Links mit “-” (Bindestrich) geschrieben werden.

Beim Bauen der Dokumentation ist dann noch aufgefallen, dass einige Ziele von Links (id) gar nicht gesetzt waren, also mussten diese auch noch angepasst werden:

       <row>
-       <entry role="func_table_entry"><para role="func_signature">
+       <entry id="pg-backup-start" role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>pg_backup_start</primary>

Qualitätssicherung

Wenn alle Änderungen vorgenommen sind, geht es an die Qualitätskontrolle. Dazu baut man die Dokumentation lokal:

$ cd postgresql
$ ./configure
$ cd doc
$ make

Wie das im genau im Detail funktioniert, ist hier beschrieben.

Falls der Build noch Fehler findet, werden diese angezeigt und der Build wird abgebrochen. Falls alles sauber durch läuft, kann man mit dem Browser seiner Wahl, jetzt noch schauen, ob auch alles wirklich so funktioniert, wie man sich das vorstellt:

$ firefox src/sgml/html/warm-standby.html

Was ich später noch gefunden habe:

Building the documentation can take very long. But there is a method to just check the correct syntax of the documentation files, which only takes a few seconds: [ 5 ]

$ make check
make -C ../src/backend generated-headers
make[1]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend'
make -C ../include/catalog generated-headers
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog'
make[2]: Nothing to be done for 'generated-headers'.
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/include/catalog'
make -C nodes generated-header-symlinks
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes'
make[2]: Nothing to be done for 'generated-header-symlinks'.
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/nodes'
make -C utils generated-header-symlinks
make[2]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils'
make -C adt jsonpath_gram.h
make[3]: Entering directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt'
make[3]: 'jsonpath_gram.h' is up to date.
make[3]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils/adt'
make[2]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend/utils'
make[1]: Leaving directory '/home/oli/fromdual/postgresql/docu/postgresql/src/backend'
rm -rf '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install
/usr/bin/mkdir -p '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log
make -C '..' DESTDIR='/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install install >'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/install.log 2>&1
make -j1  checkprep >>'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/install.log 2>&1
PATH="/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/bin:/home/oli/fromdual/postgresql/docu/postgresql/doc:$PATH" LD_LIBRARY_PATH="/home/oli/fromdual/postgresql/docu/postgresql/tmp_install/usr/local/pgsql/lib:$LD_LIBRARY_PATH" INITDB_TEMPLATE='/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/initdb-template  initdb --auth trust --no-sync --no-instructions --lc-messages=C --no-clean '/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/initdb-template >>'/home/oli/fromdual/postgresql/docu/postgresql'/tmp_install/log/initdb-template.log 2>&1

Patch einreichen

Wenn alles wie vorgesehen und zur Zufriedenheit funktioniert, kann man dann daran gehen, den Patch zu erstellen um ihn einzureichen:

$ git commit -m 'some references on variables and functions added'
$ git format-patch -1 HEAD

Dabei wird eine Datei erstellt, die den Commit-Kommentar enhält: 0001-some-references-on-variables-and-functions-added.patch.

Jetzt ist es im PostgreSQL-Projekt anscheinend so, dass man keinen Merge-Request erstellt um den Patch in den Quellcode zurück gelangen zu lassen sondern so, dass der Patch an die entsprechende Mailingliste geschickt werden muss und anschliessend von einem Entwickler, der Merge/Commit-Rechte hat, in den Haupt-Baum eingepflegt wird. Ich habe mich jetzt mal mit “meinem” Commiter darauf geeinigt, dass wir die Diskussion über meinen Patch auf der pgsql-docs Mailingliste führen.

Mal schauen, wie es weiter geht und wie weit ich mit meinem Patch komme…