Skip to content

Release-Prozess für FAQs

Die Überschrift klingt etwas bombastischer, als der Inhalt es ist …

Seit etlichen Jahren nutze ich git zur Verwaltung sowohl meiner Software als auch für die von mir betreuten FAQs. Da lag es nahe, auch die Veröffentlichung neuer Fassungen derselben (“Releases”) nach Möglichkeit zu automatisieren. Für Software bedeutet das, die einzelnen Bestandteile in einen Tarball zu packen, vielleicht Readme-Dateien zu erstellen, usw.; für FAQs ist ggf. zur reinen Textfassung eine HTML-Fassung zu erstellen, was sich insbesondere anbietet, wenn die Textfassung bereits aus Markdown besteht. :-)

Für meine alten Webseiten hatte ich einige entsprechende Scripts geschrieben - eine Textdatei (FAQ) aus einem Git-Repository zu holen und daraus ggf. noch eine HTML-Datei zu erstellen ist ja nun kein Hexenwerk. Bisher geschah das einfach “live” auf dem Webserver. Für meine neue Homepage war es mir aber wichtig, die gesamte Webpräsenz jederzeit neu generieren zu können, und das wiederum erforderte, dass sich die “fertige” FAQ (Text und HTML) dann auch im Repository für die Webseiten findet - oder von nanoc aus diesem erzeugt werden kann.

Derzeitiger Stand

Daher gibt es jetzt ein nanoc-Kommando, das diese Aufgaben wahrnimmt:

  • Optional wird als erstes das Webseiten-Repository frisch ausgescheckt (d.h. dis bisherige Fassung gelöscht und durch eine komplett neue ersetzt).

  • Dann wird die betreffende FAQ ausgecheckt, entweder als Textdatei gleichen Namens wie das Repository, oder als Textdatei aus meinem Repository für vermischte kleine FAQs. In jedem Fall erhält sie die Endung .md für Markdown.

  • Die Metadaten für die FAQ - die vor dem ersten Checkout angelegt sein müssen - werden aktualisiert, insbesondere Änderungsdatum und Version, soweit vorhanden.

  • Danach werden die Änderungen ins Repository committed und können dann entweder nochmals geprüft oder direkt “in einem Rutsch” in das Webseiten-Repository gepushed werden.

nanoc selbst wiederum erzeugt aus jeder FAQ eine Textfassung - so wie sie im Repository liegt - und, wenn dies nicht unterdrückt wird, auch eine HTML-Fassung, die dann in die Navigation eingebunden wird. Dabei werden die “Pseudo-Header” am Anfang einer FAQ (Posting-frequency oder Last-modified) entfernt. Die Veröffentlichung einer HTML-Fassung erfolgt derzeit aber nur, wenn die Textfassung auch wirklich Markdown ist - das gilt bisher noch nicht für alle FAQs.

Die notwendigen Metadaten stecken in einer gleichnamigen .yaml-Datei, die für nanoc Teil der FAQ ist. Ebenso habe ich das im übrigen auch für alle Downloads (PDF-Dateien, Tarballs o.ä.) gelöst: es gibt immer eine gleichnamige Datei mit der Endung .yaml, die Informationen über den Bearbeitungsstand, die Versionsnummer oder (bei Software) auch das Repository und den Bugtracker enthält. Mit diesen Metadaten können dann Download-Links und Infokästen erzeugt werden.

Überlegungen für die Zukunft

Zukünftig würde ich gerne auch HTML-Fassungen der anderen FAQs erzeugen, möglicherweise dann nicht aus einer Textfassung, die aus Markdown besteht, sondern aus einem übergeordneten Format (Asciidoc?), aus dem sich HTML und eine etwas ansehnlichere Textfassung als Markdown mit komplexen Formatierungen erzeugen lassen.

Und der deutlich aufwendigere zweite Teil des “Release-Managements” wird dann die Erzeugung von Software-Releases sein, nach Möglichkeit mit einem generischen Script. Dazu gehört nicht nur das Erzeugen eines Tarballs (ggf. nur mit den Dateien, die auch zum Release gehören), sondern auch das Umkopieren älterer Fassungen und das Aktualisieren der Metadaten. Letzteres wird sich grundsätzlich wie bei FAQs lösen lassen, erfordert aber das Auslesen der Daten, die sich bei einer FAQ in den Pseudo-Headern finden, namentlich der Version und des Release-Datums. In einem weiteren Schritt wäre es dann auch schon, wenn aus README-Dateien automatisch Webseiten als Bestandteil meiner Webpräsenz erzeugt würden. Theoretisch ist das alles denkbar, praktisch werde ich darüber auch tatsächlich noch einige Zeit nachdenken müssen. :-)

Insoweit ist es vielleicht ganz gut, dass ich derzeit gar keine Zeit habe, irgendwelche Programme zu schreiben …

Trackbacks

Netz - Rettung - Recht am : FAQ-Updates

Vorschau anzeigen
Heute standen wieder einmal Updates vieler - fast aller - meiner ins Usenet geposteten FAQs an. Die Löschung einer Newsgroup war der konkrete Anlass für einige Änderungen, und es lohnte sich dann, auch bei den anderen FAQs die in den letzten Monaten - tei

Kommentare

Ansicht der Kommentare: Linear | Verschachtelt

Noch keine Kommentare

Kommentar schreiben

HTML-Tags werden in ihre Entities umgewandelt.
Markdown-Formatierung erlaubt
Standard-Text Smilies wie :-) und ;-) werden zu Bildern konvertiert.
BBCode-Formatierung erlaubt
Gravatar, Identicon/Ycon Autoren-Bilder werden unterstützt.
Formular-Optionen